Driver

class pyjoulescope_driver.Driver

The Joulescope driver class.

Parameters:

timeout – The optional timeout for open. None (default) uses the default timeout.

close(device_prefix, timeout=None)

Close an attached device.

Parameters:

• device_prefix – The prefix name for the device.

• timeout – The timeout in seconds. None uses the default timeout.

device_paths(timeout=None)

List the currently connected devices.

Parameters:

timeout – The timeout in seconds. None (default) uses the default timeout.

Returns:

The list of device path strings.

finalize(timeout=None)

Finalize the driver.

Parameters:

timeout – The timeout in seconds. None (default) uses the default timeout.

log_level

The current log level.

See LogLevel.

open(device_prefix, mode=None, timeout=None)

Open an attached device.

Parameters:

• device_prefix – The prefix name for the device.

• mode –

  The open mode which is one of: * ‘defaults’: Push state to the device: the host’s retained

  value for each writable topic when present, else the metadata default.

  • ’restore’: Push nothing; adopt the device’s current state into the host cache.

  • ’raw’: Open the device in raw mode for development or firmware update.

  • None: equivalent to ‘defaults’.

• timeout – The timeout in seconds. None uses the default timeout.

publish(topic: str, value, timeout=None)

Publish a value to a topic.

Parameters:

• topic – The topic string.

• value – The value, which must pass validation for the topic.

• timeout – The timeout in seconds. None (default) uses the default timeout.

Raise:

On error.

publish_and_wait(publish_topic, publish_value, response_topic, timeout=None)

Publish a value and wait for a response on another topic.

Parameters:

• publish_topic – The topic to publish to.

• publish_value – The value to publish.

• response_topic – The topic to subscribe to for the response.

• timeout – The timeout in float seconds. None (default) uses the default timeout.

Returns:

The value received on response_topic.

Raises:

TimeoutError – If no response arrives in time.

query(topic: str, timeout=None)

Query the value for a topic.

Parameters:

• topic – The topic name.

• timeout – The timeout in seconds. None (default) uses the default timeout.

Returns:

The value for the topic.

Raise:

On error.

subscribe(topic: str, flags, fn, timeout=None)

Subscribe to receive topic updates.

Parameters:

• self – The driver instance.

• topic – Subscribe to this topic string.

• flags –

  The flags or list of flags for this subscription. The flags can be int32 jsdrv_subscribe_flag_e or string mnemonics, which are:

  • pub: Subscribe to normal values

  • pub_retain: Subscribe to normal values and immediately publish all matching retained values. With timeout, this function does not return successfully until all retained values have been published.

  • metadata_req: Subscribe to metadata requests (not normally useful).

  • metadata_rsp: Subscribe to metadata updates.

  • metadata_rsp_retain: Subscribe to metadata updates and immediately publish all matching retained metadata values.

  • query_req: Subscribe to all query requests (not normally useful).

  • query_rsp: Subscribe to all query responses.

  • return_code: Subscribe to all return code responses.

• fn – The function to call on each publish. Note that python dynamically constructs bound methods. To unsubscribe a method, provide the exact same bound method instance to unsubscribe.

• timeout – The timeout in float seconds to wait for this operation to complete. None waits the default amount. 0 does not wait and subscription will occur asynchronously.

Raises:

RuntimeError – on subscribe failure.

unsubscribe(topic, fn, timeout=None)

Unsubscribe from a topic.

Parameters:

• topic – The topic name string.

• fn – The function previously provided to subscribe().

• timeout – The timeout in seconds. None (default) uses the default timeout.

Raise:

On error.

unsubscribe_all(fn, timeout=None)

Unsubscribe a callback from all topics.

Parameters:

• fn – The function previously provided to subscribe().

• timeout – The timeout in seconds. None (default) uses the default timeout.

Raise:

On error.

class pyjoulescope_driver.ElementType

The element type enumeration.

class pyjoulescope_driver.ErrorCode

The error code enumeration.

class pyjoulescope_driver.Field

The field enumeration.

class pyjoulescope_driver.LogLevel

The log level enumeration.

class pyjoulescope_driver.MemClient(driver, device_path, cmd_topic, target=0)

Generic mb_stdmsg_mem_s protocol client.

Parameters:

• driver – The Driver instance.

• device_path – The device path (e.g. ‘u/js320/000000’).

• cmd_topic – The memory command sub-topic (e.g. ‘s/flash/!cmd’).

• target – The target memory region ID (0-255).

cmd(op, offset=0, length=0, data=b'', timeout_ms=5000, target=None)

Send a memory command and wait for the response.

Parameters:

• op – The memory operation (MEM_OP_READ, etc.).

• offset – The byte offset within the target region.

• length – The operation length in bytes.

• data – The payload data for write operations.

• timeout_ms – The device-side timeout in milliseconds.

• target – Override the instance target for this call.

Returns:

The response data bytes.

Raises:

• TimeoutError – If no response within timeout.

• RuntimeError – If the device returns a non-zero status.

erase_64k(offset)

Erase a 64 KB block.

Parameters:

offset – The block-aligned byte offset.

read(offset, length)

Read data in 256-byte page chunks.

Parameters:

• offset – The starting byte offset.

• length – The number of bytes to read.

Returns:

The read bytes.

read_personality()

Read the public mb_personality_app_s from the sys task.

The MemClient must be pointed at the sys task command topic (e.g. MemClient(driver, device, 'c/sys/!cmd')).

Returns:

A dict with the public personality fields.

Raises:

ValueError – If the response is too short.

write_pages(offset, data)

Write data in 256-byte page chunks.

Parameters:

• offset – The starting byte offset.

• data – The bytes to write.

write_verify(offset, data, retries=3)

Erase, write, and verify with retries.

Parameters:

• offset – The flash byte offset.

• data – The data to write.

• retries – Number of attempts before raising.

Raises:

RuntimeError – If verification fails after all retries.

write_verify_records(records, retries=3)

Erase, write, and verify multiple records with retries.

Parameters:

• records – The list of (offset, data) pairs.

• retries – Number of attempts before raising.

Raises:

RuntimeError – If verification fails after all retries.

class pyjoulescope_driver.StdMsg

Binary value published as JSDRV_UNION_STDMSG.

Use this instead of bytes when publishing a value that starts with an mb_stdmsg_header_s so the device receives it as MB_VALUE_STDMSG.

class pyjoulescope_driver.SubscribeFlags

The available subscribe flags.

class pyjoulescope_driver.TimeMap

Python wrapper for jsdrv_tmap_s instance.

Each instance owns its underlying jsdrv_tmap_s. TimeMap values returned from driver responses are independent snapshots; copy() and deepcopy() produce further independent instances.

time_map_get(index=None)

Get the time map data.

Parameters:

index –

The index for the time map which is one of: - None: return all time maps in the instance. - int index: Return only this index. - (int start_index, int end_index): Return this range.

start_index is inclusive, end_index is exclusive.

Returns:

Return an np.ndarray with the the named columns [‘offset_time’, ‘offset_counter’, ‘counter_rate’]. Access as either a[0][‘offset_counter’] or a[0][1].