Welcome to VESNA ALH tools’s documentation!

The vesna-alh-tools provides utilities and Python modules for managing, accessing and experimenting with VESNA-based wireless sensor networks that are using the ALH protocol.

This document provides reference documentation for Python modules that provide convenient access to resources exposed on sensor nodes. As such it is intended for users of the testbed that want to control their experiments from Python scripts.

Reference documentation is also available in Python docstrings that are accessible through the pydoc command-line tool.

For a step-by-step tutorial on how to use Python modules with the LOG-a-TEC cognitive radio testbed, see the Fed4FIRE tutorial.

Command-line utilities, contained in the same package, are intended for use by testbed administrators. Their use is outside of the scope of this document. Utilities are briefly documented in the README.

For a JavaScript library that is roughly equivalent to Python modules provided here, see the vesna-alh-js package.

Contents:

Basic ALH access

The following classes provide basic access to the resources on sensor nodes available through the ALH protocol.

ALH protocol implementations

class vesna.alh.ALHTerminal(f)

ALH protocol implementation through a serial terminal.

This implementation is used for testing and debugging when a sensor node is connected directly to a computer over a serial line.

Parameters:f – path to the character device of the terminal (usually an instance of the serial.Serial class)
get(*args, **kwargs)

Issue a GET request to the service.

Raises an ALHException in case of an error.

Parameters:
  • resource – resource to issue request to
  • args – arbitrary string arguments for the request
Returns:

vesna.alh.ALHResponse object
post(*args, **kwargs)

Issue a POST request to the service

Raises an ALHException in case of an error.

Parameters:
  • resource – resource to issue request to
  • data – POST data to attach to the request
  • args – arbitrary string arguments for the request
Returns:

vesna.alh.ALHResponse object
class vesna.alh.ALHWeb(base_url, cluster_id)

ALH protocol implementation through the HTTP infrastructure server.

ALHWeb is typically used to access the coordinator of a ZigBee mesh network.

If the API end-point is using basic authentication, you will be prompted for credentials on the command line.

You can also save credentials into either a file named .alhrc in your home directory or alhrc in the current directory. Format of the file is as in the following example:

Host example.com
User <username>
Password <password>
# more Host, User, Password lines can follow
Parameters:
  • base_url – base URL of the HTTP API (e.g. https://crn.log-a-tec.eu/communicator)
  • cluster_id – numerical cluster id
get(*args, **kwargs)

Issue a GET request to the service.

Raises an ALHException in case of an error.

Parameters:
  • resource – resource to issue request to
  • args – arbitrary string arguments for the request
Returns:

vesna.alh.ALHResponse object
post(*args, **kwargs)

Issue a POST request to the service

Raises an ALHException in case of an error.

Parameters:
  • resource – resource to issue request to
  • data – POST data to attach to the request
  • args – arbitrary string arguments for the request
Returns:

vesna.alh.ALHResponse object
class vesna.alh.ALHProxy(alhproxy, addr)

ALH protocol implementation through an ALH proxy.

This implementation forwards arbitrary ALH requests through the “nodes” resource on an ALH service used as a proxy.

ALHProxy is typically used to access nodes on the ZigBee mesh network behind the coordinator.

Parameters:
  • alhproxy – ALH implementation used as a proxy
  • addr – ZigBee address of the node to forward requests to
get(*args, **kwargs)

Issue a GET request to the service.

Raises an ALHException in case of an error.

Parameters:
  • resource – resource to issue request to
  • args – arbitrary string arguments for the request
Returns:

vesna.alh.ALHResponse object
post(*args, **kwargs)

Issue a POST request to the service

Raises an ALHException in case of an error.

Parameters:
  • resource – resource to issue request to
  • data – POST data to attach to the request
  • args – arbitrary string arguments for the request
Returns:

vesna.alh.ALHResponse object

Response class

class vesna.alh.ALHResponse(content)

This class represents the response of a resource handler.

The ALH protocol does not define the encoding of strings passed thorugh it. It can be used for binary data as well. In practice however, most strings are 7-bit ASCII. Hence this class provides ASCII-decoded form of the response for convenience, as well as the undecoded binary.

text

Text form of the response (ASCII).

content

Binary form of the response (bytes object on Python 3).

Exception classes

class vesna.alh.ALHException

Base class for errors related to the ALH protocol

Wrappers for radio hardware

The following classes provide wrappers around certain ALH resources related to experimental radios available on sensor nodes.

Spectrum sensing

class vesna.alh.spectrumsensor.SpectrumSensor(alh)

ALH node acting as a spectrum sensor.

Parameters:alh – ALH implementation used to communicate with the node
get_config_list()

Query and return the list of supported device configurations.

Returns:a ConfigList object
is_complete(program)

Return true if given program has been successfuly completed.

Parameters:program – a SpectrumSensorProgram object
program(program)

Send the given spectrum sensing program to the node.

Parameters:program – a SpectrumSensorProgram object
retrieve(program)

Retrieve results from the given spectrum sensing program.

Parameters:program – a SpectrumSensorProgram object
Returns:a SpectrumSensorResult object
sweep(sweep_config)

Perform a single frequency sweep and return results immediately

Parameters:sweep_config – frequency sweep configuration to use, a SweepConfig object
class vesna.alh.spectrumsensor.SpectrumSensorProgram(sweep_config, time_start, time_duration, slot_id)

Describes a single spectrum sensing task.

Parameters:
  • sweep_config – frequency sweep configuration to use, a SweepConfig object
  • time_start – time to start the task (UNIX timestamp)
  • time_duration – duration of the task in seconds
  • slot_id – numerical slot id used for storing measurements
class vesna.alh.spectrumsensor.SpectrumSensorResult(program)

Result of a spectrum sensing task.

get_data()

Return power measurements in dbm in form a two-dimensional array.

get_hz_list()

Return a list of frequencies in hertz covered by this result.

get_s_list()

Return a list of timestamps in seconds covered by this result.

write(path)

Write measurements into a tab-separated-values file.

Parameters:path – path to the file to write
class vesna.spectrumsensor.ConfigList

List of devices and device configurations supported by attached hardware.

get_config(device_id, config_id)

Return the specified device configuration.

Parameters:
  • device_id – numeric device id, as returned by the list command
  • config_id – numeric configuration id, as returned by the list command
get_sweep_config(start_hz, stop_hz, step_hz, name=None)

Return best frequency sweep configuration for specified requirements.

Parameters:
  • start_hz – lower bound of the frequency band to sweep (inclusive)
  • stop_hz – upper bound of the frequency band to sweep (inclusive)
  • step_hz – preferred frequency step to use
  • name – optional required sub-string in device configuration name
class vesna.spectrumsensor.Device(id, name)

A spectrum sensing device.

A particular hardware model can have one or more physical spectrum sensing devices, each of which can support one or more configurations.

class vesna.spectrumsensor.DeviceConfig(id, name, device)

Configuration for a spectrum sensing device.

The set of possible configurations for a device is usually hardware-dependent (i.e. a configuration usually reflects physical hardware settings) A configuration defines the usable frequency range, resolution bandwidth and sweep time for a device.

By convention, when specifying channel ranges, the range is given in the same format as for the range built-in (i.e. inclusive lower bound inclusive, exclusive upper bound). When specifiying frequency ranges, both bounds are inclusive.

ch_to_hz(ch)

Convert channel number to center frequency in hertz.

covers(start_hz, stop_hz)

Return true if this configuration can cover the given frequency band.

Parameters:
  • start_hz – lower bound of the frequency band to check (inclusive)
  • stop_hz – upper bound of the frequency band to check (inclusive)
get_full_sweep_config(step_hz=None)

Return a sweep configuration that covers the entire frequency range supported by this device configuration.

Parameters:step_hz – frequency step to use (by default, step by a single channel)
get_start_hz()

Return the lowest settable frequency.

get_stop_hz()

Return the highest settable frequency.

get_sweep_config(start_hz, stop_hz, step_hz)

Return a sweep configuration that covers the specified frequency band.

Parameters:
  • start_hz – lower bound of the frequency band to sweep (inclusive)
  • stop_hz – upper bound of the frequency band to sweep (inclusive)
  • step_hz – sweep frequency step
hz_to_ch(hz)

Convert center frequency in hertz to channel number.

class vesna.spectrumsensor.SweepConfig(config, start_ch, stop_ch, step_ch, nsamples=100)

Frequency sweep configuration for a spectrum sensing device.

Parameters:
  • config – device configuration object to use
  • start_ch – lowest frequency channel to sweep
  • stop_ch – one past the highest frequency channel to sweep
  • step_ch – how many channels in a step
  • nsamples – how many samples to average per measurement (only supported on some devices)
get_ch_list()

Return a list of channels covered by this configuration

get_hz_list()

Return a list of frequencies covered by this configuration

Signal generation

class vesna.alh.signalgenerator.SignalGenerator(alh)

ALH node acting as a signal generator.

Parameters:alh – ALH implementation used to communicate with the node
get_config_list()

Query and return the list of supported device configurations.

Returns:a ConfigList object
program(program)

Send the given signal generation program to the node.

Parameters:program – a SignalGeneratorProgram object
program_list(program_list)

Send several signal generator programs to the node.

Parameters:program_list – a list of SignalGeneratorProgram objects
class vesna.alh.signalgenerator.SignalGeneratorProgram(tx_config, time_start, time_duration)

Describes a single signal generation task.

Parameters:
  • tx_config – transmission configuration to use
  • time_start – time to start the task (UNIX timestamp)
  • time_duration – duration of the task in seconds
class vesna.alh.signalgenerator.ConfigList

List of devices and device configurations supported by attached hardware.

get_config(device_id, config_id)

Return the specified device configuration.

Parameters:
  • device_id – numeric device id, as returned by the list command
  • config_id – numeric configuration id, as returned by the list command
get_tx_config(f_hz, power_dbm, name=None)

Return best transmission configuration for specified requirements.

Parameters:
  • f_hz – transmission frequency
  • power_dbm – transmission power
  • name – optional required sub-string in device configuration name
class vesna.alh.signalgenerator.Device(id, name)

A signal generation device.

A particular hardware model can have one or more physical signal generation devices, each of which can support one or more configurations.

class vesna.alh.signalgenerator.DeviceConfig(id, name, device)

Configuration for a signal generation device.

The set of possible configurations for a device is usually hardware-dependent (i.e. a configuration usually reflects physical hardware settings). A configuration defines the usable frequency and power range.

ch_to_hz(ch)

Convert channel number to center frequency in hertz.

covers(f_hz, power_dbm)

Return true if this configuration can support the given frequency and power.

Parameters:
  • f_hz – transmission frequency in hertz
  • power_dbm – transmission power in dBm
get_start_hz()

Return the lowest settable frequency.

get_stop_hz()

Return the highest settable frequency.

get_tx_config(f_hz, power_dbm)

Return the transmission configuration for the given frequency and power.

Parameters:
  • f_hz – transmission frequency in hertz
  • power_dbm – transmission power in dBm
class vesna.alh.signalgenerator.TxConfig(config, f_ch, power_dbm)

Transmission configuration for a signal generation device.

Parameters:
  • config – DeviceConfig device configuration object to use
  • f_ch – frequency channel for transmission
  • power_db – power level for transmission

UWB node

class vesna.alh.uwbnode.UWBNode(alh)

ALH node abstracting an UWB node functionality

Parameters:alh – ALH implementation used to communicate with the node
check_pending_measurement()

check if measurement data is ready for transfer

get_last_range_data()

return measurements data

get_radio_settings()

read current uwb radio settings

get_sensor_id()

read the ID of UWB node

setup_radio(settings)

setup radio from RadioSettings object

OMF helpers

The following classes help with the integration with the OMF framework.

class vesna.omf.ALH(cluster_uid=None, socket_path=None)

ALH protocol implementation for access through the OMF framework.

This class is typically used to access the coordinator when accessing the tesbed through the OMF framework. No parameters are usually needed for the constructor. The appropriate values are discovered automatically through OMF.

get(*args, **kwargs)

Issue a GET request to the service.

Raises an ALHException in case of an error.

Parameters:
  • resource – resource to issue request to
  • args – arbitrary string arguments for the request
Returns:

vesna.alh.ALHResponse object
post(*args, **kwargs)

Issue a POST request to the service

Raises an ALHException in case of an error.

Parameters:
  • resource – resource to issue request to
  • data – POST data to attach to the request
  • args – arbitrary string arguments for the request
Returns:

vesna.alh.ALHResponse object

Indices and tables