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, platform=None, token=None, debug_peripheral=False)

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
  • uart_output_file – If print_uart is True, sets the UART output file. Default is stdout.
  • 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. Available values are: “nrf52832” and “stm32f4”. If no platform is specified and board.json is not used, “nrf52832” is assumed.
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.

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() command from jumper.h
is_running()

Checks if the virtual device has been started.

Returns:True if running or pause, 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)
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