Vlab

class jumper.Vlab(working_directory=None, config_file=None, gdb_mode=False, sudo_mode=False, registers_trace=False, functions_trace=False, interrupts_trace=False, trace_output_file=None, print_uart=False, uart_output_file=None, uart_device=False, platform=None, token=None, debug_peripheral=False, gpio=False, stack_max=False, code_coverage=False, print_mips=False, uarts_to_print=[])

The main class for using Jumper Virtual Lab

Parameters:
  • working_directory – The directory that holds the board.json abd scenario.json files for the virtual session
  • config_file – Config file holding the API token (downloaded from https://vlab.jumper.io)
  • gdb_mode – If True, a GDB server will be opened on port 5555
  • sudo_mode – If True, firmware can write to read-only registers. This is useful for injecting a mock state to the hardware.
  • registers_trace – Adds a trace for CPU registers values before every CPU instruction.
  • functions_trace – Adds a trace for the the functions that are being executed (requires a .out or .elf file)
  • interrupts_trace – Adds a trace for interrupts handling.
  • trace_output_file – If traces_list is not empty, redirects the trace from stdout to a file.
  • print_uart – If True UART prints coming from the device will be printed to stdout or a file.
  • uarts_to_print – List of uarts that will be print to stdout, in case print_uart=True. If the list is empty and print_uart=True, all the uarts print.
  • uart_output_file – If print_uart is True, sets the UART output file. Default is stdout.
  • uart_device – If True, a “uart” file will be created in the working directory which is linked to the virtual UART device. Can be used with “screen”. Linux only
  • token – The API token to be used for authentication. If not specified, the token in ~/.jumper/config.json will be used.
  • platform – Emulated platform, should only be when no board.json file exists in the working directory. If no platform is specified and board.json is not used, “nrf52832” is assumed.
  • print_mips – If True, print MIPS (Million instructions per second) when emulation is finished.
get_device_time_ms()

How much time passed from beginning of the emulation.

Returns:Emulation time in milliseconds.
get_device_time_ns()

How much time passed from beginning of the emulation.

Returns:Emulation time in nanoseconds.
get_device_time_us()

How much time passed from beginning of the emulation.

Returns:Emulation time in microseconds.
get_pin_level(pin_num)

Specifies get the pin level for a pin num.

Parameters:num (pin) – pin number id
get_return_code()

Checks a return code from the device. Raises EmulationError if a failure occured during execution

Returns:
  • 0 if device was stopped using the stop() method
  • Exit code from firmware if the Device exited using the jumper_sudo_exit_with_exit_code() - None if the virtual device is still running command from jumper.h
is_running()

Checks if the virtual device has been started.

Returns:True if running or paused, False otherwise.
load(file_path)

Loads firmware to a virtual device and initialises a Virtual Lab session. Use start() to start an emulation after this method was called.

Parameters:file_path – Path for a firmware file (supported extensions are bin, out, elf, hex)
on_bkpt(callback)

Sets a callback to be called when the virtual device execution reaches a BKPT assembly instruction.

Parameters:callback – The callback to be called. Callback will be called with callback(code) where code is the code for the BKPT instruction.
on_interrupt(callback)
Parameters:callback – The callback to be called when an interrupt is being handled. The callback will be called with callback(interrupt)
on_pin_level_event(callback)

Specifies a callback for a pin transition event.

Parameters:callback – The callback to be called when a pin transition occures. The callback will be called with callback(pin_number, pin_level, time)
on_uart_read_line(callback)

Specifies a callback for a uart read line.

Parameters:callback – The callback to be called when a line exist in the buffer. The callback will be called with callback(line)
pause()

Pause the device.

resume()

Resumes a paused device.

run_for_ms(ms)

Starts or resumes the virtual device, the device will halt after the amount of time specified.

This function is blocking until the virtual device has halted. Use this when the virtual device is stopped or halted.

Parameters:ms – Time to run in ms
run_for_ns(ns)

Starts or resumes the virtual device, the device will halt after the amount of time specified.

This function is blocking until the virtual device has halted. Use this when the virtual device is stopped or halted.

Parameters:ns – Time to run in ns
run_for_us(us)

Starts or resumes the virtual device, the device will halt after the amount of time specified.

This function is blocking until the virtual device has halted. Use this when the virtual device is stopped or halted.

Parameters:ms – Time to run in us
start(ns=None)

Starts the emulation

Parameters:ns

If provided, commands the virtual device to run for the amount of time given in ns and then halt.

If this parameter is used, this function is blocking until the virtual devices halts, if None is given, this function is non-blocking.

stop()

Stops the Virtual Lab session.

Opposing to halting the session, the virtual device cannot be resumed after a stop command.

uart

The main UART device for the Virtual Lab session

Returns:JemuUart