Wishful Upi packages

There are in total 2 major categories of UPIs, namely the UPI_R (physical and MAC layer control) and the UPI_N (network layer control). The implemented framework offers the possibility to execute the supported UPI_R and UPI_N from a global controller through the use of UPI_G or from a local controller through the usage of UPI_L. Also a hierarchical interface for the exchange of messages between local and global control programs.

Submodules

UPI_M: Management interface

The UPI_M is used to enable the use of a specific execution enviroment in a node and also for the initialization of nodes before starting an experiment. MAC protocol update will also be supported in the next version of the interface based on the supported MAC engines.

The WISHFUL interface definitions - UPIs (UPI_M) for install/update/active/deactive software modules.

wishful_upis.mgmt.add_rule(rule)

Add new rule to rule-matching engine

wishful_upis.mgmt.delete_rule(rule_id)

Remove rule to rule-matching engine

wishful_upis.mgmt.start_local_control_program(program_name, program_code)

Install and execute a given control program on a local node remotely.

Args:

program_name (string): The name of the local CP. program_code (function): A python function containing the local CP control logic.

wishful_upis.mgmt.stop_local_control_program(program_id)

Stops execution of a given control program on loca/remote node.

wishful_upis.mgmt.send_msg_to_local_control_program(program_id, msg)

Hierarchical control function allows the global control program to send messages to local control programs.

wishful_upis.mgmt.transaction_begin()

Start a transaction

i.e. all subsequent UPI calls are executed in transactional scope.

wishful_upis.mgmt.transaction_abort()

Aborts a running transaction

i.e. all changes are roll backed.

wishful_upis.mgmt.transaction_commit()

Commit an open transaction.

UPI_N: Network layer programming interfaces

Unified Programming Interface – Network(UPI_N) : this is a software interface consisting of a set of functions that ensures uniform control of the upper MAC and network layer protocol behavior on heterogeneous devices. The functions forming the interface are generic, their implementation is hardware and platform specific and is provided by the Local Monitoring and Configuration engine. The user is able to manipulate a wide range of network layer fucntionality like routing, flow control, queue management, priority control and more.

wishful_upis.net.set_parameters(param_key_values_dict)

The UPI_N interface is able to configure the protocol (routing, transport, application) behavior by changing parameters. Parameters correspond to the variables used in the protocols. This function (re)set the value(s) of the parameters specified in the dictionary argument. The list of available parameters supported by all platforms/OS are defined in this module. Parameters specific to a subgroup of platforms/OS are defined in the corresponding submodules. A list of supported parameters can be dynamically obtained using the get_info function on each module.

Examples:

>> param_key_values = {ROUTING_MAX_TTL : 5}
>> result = control_engine.net.set_parameters(param_key_values)
>> print result
{ROUTING_MAX_TTL : 0}

Args:

param_key_values_dict (dict): dictionary containing the key (string) value (any) pairs for each parameter.

An example is {CSMA_CW : 15, CSMA_CW_MIN : 15, CSMA_CW_MAX : 15}

Returns:

dict: A dictionary containing key (string name) error (0 = success, 1=fail, +1=error code) pairs for each parameter.

wishful_upis.net.get_parameters(param_key_list)

Get the parameter on higher layers of protocol stack (higher MAC and above)

Args:

param_key: the parameter identified by this key.

Returns:

the parameter value

wishful_upis.net.get_measurements(measurement_key_list)

Examples:

>> measurement_keys = [NUM_FREEZING_COUNT]
>> result = control_engine.net.iface("wlan0").get_measurements(measurement_keys)
>> print result
{UPI_RN.NUM_FREEZING_COUNT : 150}

Args:

measurement_key_list (list): list of requested measurements, an example of is [NUM_FREEZING_COUNT, TX_ACTIVITY].

Returns:

dict: A dictionary containing key (string name) and values of the requested measurements.

wishful_upis.net.get_measurements_periodic(measurement_key_list, collect_period, report_period, num_iterations, report_callback)

Examples:

>> def my_cb(report):
>>     for key in report.keys():
>>         for measurement in report[key]:
>>             print measurement
>> measurement_keys = [NUM_FREEZING_COUNT, TX_ACTIVITY]
>> result = control_engine.radio.iface("wlan0").get_measurements_periodic(measurement_keys,1000000,5000000,10,my_cb)
>> print result
{UPI_RN.NUM_FREEZING_COUNT : 150}

Args:

measurement_key_list (list): list of measurement keys. The keys are measurement names defined in this module. collect_period (int): defines the time between two consecutive measurement readings, in microsecond. report_period (int): defines the time between two consecutive reports to the control program, in microseconds. num_iterations (int): defines how many times the measurement collection has to be repeated. report_callback (function): the local callback that is invoked every report period.

Returns:

int: error code, 0 if success, 1 otherwise.

wishful_upis.net.subscribe_events(event_key_list, event_callback, event_duration)

Examples:

>> event_keys = ["MAC_RX_EVENT","MAC_COLLISION_EVENT"]
>> result = control_engine.radio.iface("wlan0").subscribe_events(event_keys, event_cb, 60)
>> print result
{"MAC_RX_EVENT" : 0, "MAC_COLLISION_EVENT":0}

Args:

event_key_list (list): List of events which should be monitored. event_callback (Callable): Callback called every time an event is posted. event_duration (int): Duration (in seconds) for which the event listener(s) should be active (0 = infinite)

Returns:

dict: A dictionary containing an error code for each event.

wishful_upis.net.get_network_info()

wishful_upis.net.create_packetflow_sink(port)

Start IPerf server (TCP/IP)

wishful_upis.net.destroy_packetflow_sink()

Stop IPerf server.

wishful_upis.net.start_packetflow(dest_ip, port=5001)

Start IPerf client.

wishful_upis.net.stop_packetflow()

Stop IPerf client.

wishful_upis.net.get_iface_hw_addr(iface)

Returns the hardware address (MAC address) of a given interface.

wishful_upis.net.set_ip_address(iface, ip_address)

Set ip address of the station

wishful_upis.net.get_iface_ip_addr(iface)

Returns the IP address of a given interface.

wishful_upis.net.set_ARP_entry(iface, mac_addr, ip_addr)

Manipulates the entries in the ARP cache.

wishful_upis.net.change_routing(current_gw_ip_addr, new_gw_ip_addr, device_ip_addr)

Controls the routing.

wishful_upis.net.gen_layer2_traffic(iface, num_packets, pinter, max_phy_broadcast_rate_mbps=None, **kwargs)

Inject layer2 traffic into network device.

wishful_upis.net.inject_frame(iface, frame, is_layer_2_packet, tx_count=1, pkt_interval=1)

Inject L2/L3 frame injection into the protocol stack

wishful_upis.net.sniff_layer2_traffic(iface, sniff_timeout, **kwargs)

Layer-2 packet sniffing from network device.

wishful_upis.net.set_netem_profile(iface, profile)

Set emulation profile in given network interface

wishful_upis.net.update_netem_profile(iface, profile)

Update emulation profile in given network interface

wishful_upis.net.remove_netem_profile(iface)

Remove emulation profile from given network interface.

wishful_upis.net.set_per_link_netem_profile(iface, dstIpAddr, profile)

Set emulation profile in network interface for given link identified with destination IP address

wishful_upis.net.update_per_link_netem_profile(iface, dstIpAddr, profile)

Update emulation profile in network interface for given link identified with MAC addresses.

wishful_upis.net.remove_per_link_netem_profile(iface, dstIpAddr)

Remove emulation profile from network interface for given link identified with MAC addresses.

wishful_upis.net.install_egress_scheduler(iface, scheduler)

Install Egress Scheduler in given network interface.

wishful_upis.net.remove_egress_scheduler(iface)

Remove Egress Scheduler from network interface

wishful_upis.net.clear_nf_tables(table='ALL', chain='ALL')

Clear all entries in given chain of given table in iptables

wishful_upis.net.get_nf_table(tableName)

Get specific iptable and its entires

wishful_upis.net.set_pkt_marking(flowId, markId=None, table='mangle', chain='POSTROUTING')

Add iptable rule for marking all packets belonging to flow identified with given 5-tuple

wishful_upis.net.del_pkt_marking(flowId, markId=None, table='mangle', chain='POSTROUTING')

Remove rule used to mark given flow from iptable

wishful_upis.net.set_ip_tos(flowId, tos, table='mangle', chain='POSTROUTING')

Add iptable rule for setting TOS (Type-of-Service) field in all packets matching flowID (5-tuple)

wishful_upis.net.del_ip_tos(flowId, tos, table='mangle', chain='POSTROUTING')

Remove rule used to setting TOS field from iptable

UPI_R: Radio layer programming interfaces

Unified Programming Interface – Radio (UPI_R) : this is a software interface consisting of a set of functions that ensures uniform control of the radio and lower MAC behaviour on heterogeneous devices. The functions forming the interface are generic, their implementation is hardware and platform specific and is provided by the Local Monitoring and Configuration engine. Monitoring of parameters, taking measurements at any time and total control of all exposed parameters of the afforementioned layers is made possible through UPI_R for all supported platforms, providing unprecented flexibility of control on the targeted platforms.

The WiSHFUL radio control interface, UPI_R. Used for configuration/monitoring of the lower layers of the network protocol stack (lower MAC and PHY).

Note, here all generic functions are defined, i.e. those which can be supported by any wireless networking node (IEEE 802.11, LTE, ZigBee).

All protocol-dependent functions are defined in separate folder, e.g. wifi/, lowpan/ or lte/.

wishful_upis.radio.TX_POWER = Attribute(key=TX_POWER, type=<type 'int'>, isReadonly=False)

Transmission power in dBm

wishful_upis.radio.TX_ANTENNA = Attribute(key=TX_ANTENNA, type=<type 'int'>, isReadonly=False)

Antenna number selected for transmission

wishful_upis.radio.RX_ANTENNA = Attribute(key=RX_ANTENNA, type=<type 'int'>, isReadonly=False)

Antenna number selected for reception

wishful_upis.radio.NETWORK_INTERFACE_HW_ADDRESS = Attribute(key=NETWORK_INTERFACE_HW_ADDRESS, type=<type 'int'>, isReadonly=False)

MAC address of wireless network interface card

wishful_upis.radio.TDMA_SUPER_FRAME_SIZE = Attribute(key=TDMA_SUPER_FRAME_SIZE, type=<type 'int'>, isReadonly=False)

TDMA protocol. Duration of periodic frames used for slot allocations in us

wishful_upis.radio.TDMA_NUMBER_OF_SYNC_SLOT = Attribute(key=TDMA_NUMBER_OF_SYNC_SLOT, type=<type 'int'>, isReadonly=False)

TDMA protocol. Number of slots included in a super frame

wishful_upis.radio.TDMA_ALLOCATED_SLOT = Attribute(key=TDMA_ALLOCATED_SLOT, type=<type 'int'>, isReadonly=False)

TDMA protocol. Assigned slot in a super frame

wishful_upis.radio.TDMA_MAC_PRIORITY_CLASS = Attribute(key=TDMA_MAC_PRIORITY_CLASS, type=<type 'int'>, isReadonly=False)

TDMA protocol. QUEUE class service associated with TDMA radio program

wishful_upis.radio.CSMA_BACKOFF_VALUE = Attribute(key=CSMA_BACKOFF_VALUE, type=<type 'int'>, isReadonly=False)

CSMA protocol. Backoff value

wishful_upis.radio.CSMA_CW = Attribute(key=CSMA_CW, type=<type 'int'>, isReadonly=False)

CSMA protocol.current value of the Contention Window

wishful_upis.radio.CSMA_CW_MIN = Attribute(key=CSMA_CW_MIN, type=<type 'int'>, isReadonly=False)

CSMA protocol. Minimum value of the Contention Window

wishful_upis.radio.CSMA_CW_MAX = Attribute(key=CSMA_CW_MAX, type=<type 'int'>, isReadonly=False)

CSMA protocol. Maximum value of the Contention Window

wishful_upis.radio.CSMA_TIMESLOT = Attribute(key=CSMA_TIMESLOT, type=<type 'int'>, isReadonly=False)

CSMA protocol.Duration of the backoff slot

wishful_upis.radio.CSMA_EIFS = Attribute(key=CSMA_EIFS, type=<type 'int'>, isReadonly=False)

CSMA protocol.Duration of the EIFS time

wishful_upis.radio.CSMA_DIFS = Attribute(key=CSMA_DIFS, type=<type 'int'>, isReadonly=False)

CSMA protocol.Duration of the DIFS time

wishful_upis.radio.CSMA_SIFS = Attribute(key=CSMA_SIFS, type=<type 'int'>, isReadonly=False)

CSMA protocol.Duration of the SIFS time

wishful_upis.radio.CSMA_MAC_PRIORITY_CLASS = Attribute(key=CSMA_MAC_PRIORITY_CLASS, type=<type 'int'>, isReadonly=False)

CSMA protocol.QUEUE class service associated with CSMA radio program

wishful_upis.radio.CSMA_NUM_FREEZING_COUNT = Attribute(key=CSMA_NUM_FREEZING_COUNT, type=<type 'int'>, isReadonly=True)

CSMA protocol.Total number of freezing during the backoff phase

wishful_upis.radio.NOISE = Measurement(key=NOISE, type=<type 'int'>)

Level of noise in dBm

wishful_upis.radio.CSI = Measurement(key=CSA, type=<type 'int'>)

Channel State Information’ last measured value

wishful_upis.radio.RSSI = Measurement(key=RSSI, type=<type 'int'>)

Received Signal Strength Indication (RSSI); it refers to the last received frame in dBm.

wishful_upis.radio.SNR = Measurement(key=SNR, type=<type 'int'>)

Signal-to-noise ratio (SNR) of the last received frame in dB.

wishful_upis.radio.LQI = Measurement(key=LQI, type=<type 'int'>)

Link Quality Indicator (LQI)

wishful_upis.radio.FER = Measurement(key=FER, type=<type 'int'>)

Frame Erasure Rate (FER)

wishful_upis.radio.BER = Measurement(key=BER, type=<type 'int'>)

Bit Error Rate (BER)

wishful_upis.radio.BUSY_TYME = Measurement(key=BUSY_TYME, type=<type 'int'>)

Time interval in which the transceiver has been active (including reception, transmission and carrier sense)

wishful_upis.radio.TX_ACTIVITY = Measurement(key=TX_ACTIVITY, type=<type 'int'>)

Time interval in which the transceiver has been involved in transmission.

wishful_upis.radio.LOW_LEVEL_TIME = Measurement(key=LOW LEVEL TIME, type=<type 'int'>)

Time provided by platform chipset

wishful_upis.radio.NUM_GOOD_PREAMBLE = Measurement(key=NUM_GOOD_PREAMBLE, type=<type 'int'>)

Number of preambles correctly synchronized by the receiver.

wishful_upis.radio.NUM_BAD_PREAMBLE = Measurement(key=NUM_BAD_PREAMBLE, type=<type 'int'>)

Number of receiver errors in synchronizing a valid preamble.

wishful_upis.radio.NUM_GOOD_PLCP = Measurement(key=NUM_GOOD_PLCP, type=<type 'int'>)

Number of valid PLCP synchronized by the receiver

wishful_upis.radio.NUM_BAD_PLCP = Measurement(key=NUM_BAD_PLCP, type=<type 'int'>)

Number of wrong PLCP errors triggered by the receiver

wishful_upis.radio.NUM_GOOD_CRC = Measurement(key=NUM_GOOD_CRC, type=<type 'int'>)

Number of success of CRC checks

wishful_upis.radio.NUM_BAD_CRC = Measurement(key=NUM_BAD_CRC, type=<type 'int'>)

Number of failures of CRC checks

wishful_upis.radio.NUM_TX = Measurement(key=NUM_TX, type=<type 'int'>)

Total number of transmitted frames measured since the interface has been started

wishful_upis.radio.NUM_TX_DATA_FRAME = Measurement(key=NUM_TX_DATA_FRAME, type=<type 'int'>)

Total number of transmitted frames measured since the interface has been started

wishful_upis.radio.NUM_TX_SUCCESS = Measurement(key=NUM_TX_SUCCESS, type=<type 'int'>)

Total number of successfully transmitted frame measured since the interface has been started

wishful_upis.radio.NUM_RX = Measurement(key=NUM_RX, type=<type 'int'>)

Total number of received frames since the interface has been started

wishful_upis.radio.NUM_RX_ACK_RAMATCH = Measurement(key=NUM_RX_ACK_RAMATCH, type=<type 'int'>)

Total number of received frames addressed to the node since the interface has been started. This measurement traces the number of received frame in which the receiver address field matches with the network interface card MAC address

wishful_upis.radio.NUM_RX_ACK = Measurement(key=NUM_RX_ACK, type=<type 'int'>)

Total receive ack frame measured since the interface has been started

wishful_upis.radio.NUM_RX_SUCCESS = Measurement(key=NUM_RX_SUCCESS, type=<type 'int'>)

Total number of successfully transmitted frame measured since the interface has been started

wishful_upis.radio.CHANNEL_UP = Event(key=CHANNEL_UP, type=None)

Triggered when the wireless channel switches from idle to busy

wishful_upis.radio.CHANNEL_DOWN = Event(key=CHANNEL_DOWN, type=None)

Triggered when the wireless channel switches from busy to idle

wishful_upis.radio.QUEUE_OUT_UP = Event(key=QUEUE_OUT_UP, type=None)

Triggered when the frame is injected into the physical queue of the platform from the upper MAC

wishful_upis.radio.RX_END = Event(key=RX_END, type=None)

Triggered when that receiver operation is finished

wishful_upis.radio.RX_PLCP_END = Event(key=RX_PLCP_END, type=None)

Triggered at the end of PLCP reception

wishful_upis.radio.RX_ERROR_BAD_PLCP = Event(key=RX_ERROR_BAD_PLCP, type=None)

Triggered at the occurrence of a receiver error due a PLCP check failure

wishful_upis.radio.RX_ERROR_BAD_CRC = Event(key=RX_ERROR_BAD_CRC, type=None)

Triggered at the occurrence of a receiver error due a CRC failure

wishful_upis.radio.TDMA_SLOT_START = Event(key=TDMA_SLOT_START, type=None)

Triggered at the beginning of a TDMA slot

wishful_upis.radio.TDMA_SLOT_END = Event(key=TDMA_SLOT_END, type=None)

Triggered at the end of a TDMA slot

wishful_upis.radio.set_parameters(param_key_values_dict)

The UPI_R interface is able to configure the radio and MAC behavior by changing parameters. Parameters correspond to the configuration registers of the hardware platform and to the variables used in the radio programs. This function (re)set the value(s) of the parameters specified in the dictionary argument. The list of available parameters supported by all platforms are defined in this module. Parameters specific to a subgroup of platforms are defined in the corresponding submodules. A list of supported parameters can be dynamically obtained using the get_radio_info function.

Example:

>> param_key_values = {CSMA_CW : 15, CSMA_CW_MIN : 15, CSMA_CW_MAX : 15}
>> result = control_engine.radio.iface("wlan0").set_parameters(param_key_values)
>> print result
{CSMA_CW : 0, CSMA_CW_MIN : 0, CSMA_CW_MAX : 0}

Args:

param_key_values_dict (dict): dictionary containing the key (string) value (any) pairs for each parameter.

An example is {CSMA_CW : 15, CSMA_CW_MIN : 15, CSMA_CW_MAX : 15}

Returns:

dict: A dictionary containing key (string name) error (0 = success, 1=fail, +1=error code) pairs for each parameter.

wishful_upis.radio.get_parameters(param_key_list)

The UPI_R interface is able to obtain the current radio and MAC configuration by getting parameter values. Parameters correspond to the configuration registers of the hardware platform and to the variables used in the radio programs. This function get(s) the value(s) of the parameters specified in the list argument. The list of available parameters supported by all platforms are defined in this module. Parameters specific to a subgroup of platforms are defined in the corresponding submodules. A list of supported parameters can be dynamically obtained using the get_radio_info function.

Example:

>> param_keys = [CSMA_CW,CSMA_CWMIN]
>> result = control_engine.radio.iface("wlan0").get_parameters(param_keys)
>> print result
{CSMA_CW : 15, CSMA_CWMIN : 15}

Args:

param_key_list (list): list of parameter names, an example is [UPI_RN.CSMA_CW, UPI_RN.CSMA_CW_MIN, UPI_RN.CSMA_CW_MAX].

Returns:

dict: A dictionary containing key (string name) and values of the requested parameters.

wishful_upis.radio.get_measurements(measurement_key_list)

The UPI_R interface is able to get the radio measurements in a pull based manner. The low-level measurements are continuously monitored by the hardware platform and by the radio programs. They can be used to get information and statistics about the state of the physical links or the internal state of the node. This function gets the measurements specified in the list argument and returns a dictionary with their values. The list of available measurements supported by all platforms are defined in this module. Measurements specific to a subgroup of platforms are defined in the corresponding submodules. A list of supported measurements can be dynamically obtained using the get_radio_info function.

Example:

>> measurement_keys = [NUM_FREEZING_COUNT]
>> result = control_engine.radio.iface("wlan0").get_measurements(measurement_keys)
>> print result
{UPI_RN.NUM_FREEZING_COUNT : 150}

Args:

measurement_key_list (list): list of requested measurements, an example of is [NUM_FREEZING_COUNT, TX_ACTIVITY].

Returns:

dict: A dictionary containing key (string name) and values of the requested measurements.

wishful_upis.radio.get_measurements_periodic(measurement_key_list, collect_period, report_period, num_iterations, report_callback)

The UPI_R interface is able to get the radio measurements in a pull based manner periodically. This function works similarly to get_measurements, it gets the value(s) specified in the list argument and returns a dictionary with their values, but in cycling mode. The function gets the measurements every collect_period and stores them on node memory. Every report_period all measurements are reported to the controller. This operation is performed a number of times specified by num_iterations. A callback function is used to receive the measurements results. The list of available measurements supported by all platforms are defined in this module. Measurements specific to a subgroup of platforms are defined in the corresponding submodules. A list of supported measurements can be dynamically obtained using the get_radio_info function.

Example:

>> def my_cb(report):
>>     for key in report.keys():
>>         for measurement in report[key]:
>>             print measurement
>> measurement_keys = [NUM_FREEZING_COUNT, TX_ACTIVITY]
>> result = control_engine.radio.iface("wlan0").get_measurements_periodic(measurement_keys,1000000,5000000,10,my_cb)
>> print result
{UPI_RN.NUM_FREEZING_COUNT : 150}

Args:

measurement_key_list (list): list of measurement keys. The keys are measurement names defined in this module. collect_period (int): defines the time between two consecutive measurement readings, in microsecond. report_period (int): defines the time between two consecutive reports to the control program, in microseconds. num_iterations (int): defines how many times the measurement collection has to be repeated. report_callback (function): the local callback that is invoked every report period.

Returns:

int:

• 0 if the parameter setting call was successfully performed
• 1 partial success
• 2 error.

wishful_upis.radio.subscribe_events(event_key_list, event_callback, event_duration)

The UPI_R interface is able to monitor the radio and mac behavior asynchronously through events. This function subscribes an event listener for one or more events for the specified event duration (0 = infinite). The event callback is called each time on of the event is posted. The list of available events supported by all platforms are defined in this module. Events specific to a subgroup of platforms are defined in the corresponding submodules. A list of supported events can be dynamically obtained using the get_radio_info function.

Example:

>> event_keys = ["MAC_RX_EVENT","MAC_COLLISION_EVENT"]
>> result = control_engine.radio.iface("wlan0").subscribe_events(event_keys, event_cb, 60)
>> print result
{"MAC_RX_EVENT" : 0, "MAC_COLLISION_EVENT":0}

Args:

event_key_list (list): List of events which should be monitored. event_callback (Callable): Callback called every time an event is posted. event_duration (int): Duration (in seconds) for which the event listener(s) should be active (0 = infinite)

Returns:

dict: A dictionary containing an error code for each event.

wishful_upis.radio.activate_radio_program(name)

This function activates the specified radio program. When executed, this function stops the current radio program and enables the execution of the radio program specified in the parameter name.

Example:

>> result = control_engine.radio.iface("wlan0").activate_radio_program("CSMA")
>> print result
0

Args:

name (str): String identifier of the radio program (e.g. CSMA, TDMA, TSCH)

Returns:

int:

• 0 if the parameter setting call was successfully performed
• 1 partial success
• 2 error.

wishful_upis.radio.deactivate_radio_program(name)

When executed, this function stops the radio program specified in the parameter radio_program_name.

Example:

>> result = control_engine.radio.iface("wlan0").deactivate_radio_program("CSMA")
>> print result
0

Args:

name (str): String identifier of the radio program (e.g. CSMA, TDMA, TSCH)

Returns:

int:

• 0 if the parameter setting call was successfully performed
• 1 partial success
• 2 error.

wishful_upis.radio.get_running_radio_program()

Returns active radio program.

Each radio program is associated with a name and an index. When executed, this function return the index of the radio program active.

Example:

>> args = {'interface' : 'wlan0'}
>> result = control_engine.radio.iface("wlan0").getActive(args)
>> print result
CSMA

Args:

myargs:

a dictionary data type (key: value) where the keys are: The key “interface” specify the network interface to use.

Returns:

the name of the active radio program

wishful_upis.radio.play_waveform(iface, freq, power_lvl, **kwargs)

Starts transmitting a radio waveform on signal generator

Example:

>> iface = '192.168.200.35'
>> freq = '5200'
>> power_lvl = 0
>> controller.radio.play_waveform(iface, freq, power_lvl)

Args:

iface (String): Address ip of the interface connected with the signal generator. freq (int): Frequency of the generated waveform. power_lvl (int): power level of the generated waveform. kwargs: Extra argumentes for the signal generator.

Returns:

int:

• 0 if the call was successfully performed
• 1 partial success
• 2 error.

wishful_upis.radio.stop_waveform(iface, **kwargs)

Stops the radio waveform transmitting on signal generator

Example:

>> iface = '192.168.200.35'
>> controller.radio.stop_waveform(iface)

Args:

iface (String): Address ip of the interface connected with the signal generator. kwargs: Extra argumentes for the signal generator.

Returns:

int:

• 0 if the call was successfully performed
• 1 partial success
• 2 error.

wishful_upis.radio.set_tx_power(power_dBm)

Sets the transmit power in dBm. If W is the power in Watt, the power in dBm is P = 30 + 10.log(W).

In addition auto and fixed enable and disable power control (if those features are available).

Example:

>> controller.radio.set_power("15")

Args:

power_dBm (String): Specify transmit power level in dBm and setting type

Returns:

int:

• 0 if the call was successfully performed
• 1 partial success
• 2 error.

wishful_upis.radio.get_tx_power()

Gets the current transmit power and the list of various Transmit Powers available on the device

Example:

>> power_information = controller.radio.get_power()
>> print(power_information)
current_tx_power:15
available_tx_power:8,9,10,11,12,13,14,15,16,17,18

Returns:

dictionary: transmission power values in dBm

wishful_upis.radio.get_noise()

Background noise level (when no packet is transmitted). May be arbitrary units or dBm, this framework uses driver meta information to interpret the raw value given by interface and display it.

Example:

>> noise_information = controller.radio.get_noise()
>> print(noise_information)
-80dBm

Returns:

int: noise level value

wishful_upis.radio.start_csi_measurements(callback)

Start the thread to receive the channel state information. (amplitude + phase)

When call, this UPI uses a separate thread to logs channel state estimation for each of the 56 ofdm subcarriers (HT20 case). The channel state info is the I and Q values for the subcarriers. When a burst of CSI information is ready, a callback is called.

Args:

callback (function): Specify the function to call when CSI information have been reported

Returns:

int:

• 0 if the call was successfully performed
• 1 partial success
• 2 error.

wishful_upis.radio.stop_csi_measurements()

Stop the thread to receive the channel state information. (amplitude + phase)

When call, this UPI uses a separate thread to logs channel state estimation for each of the 56 ofdm subcarriers (HT20 case). The channel state info is the I and Q values for the subcarriers. When a burst of CSI information is ready, a callback is called.

Returns:

int:

• 0 if the call was successfully performed
• 1 partial success
• 2 error.

wishful_upis.radio.get_radio_platforms()

Gets available radio platforms. The information elements used by the UPI_R interface, to manage parameters, measurements and radio program, are organized into data structures, which provide information on the platform type and radio capabilities. When executed, this function return information about available interfaces on node, the name or the identifier of the interface and the supported platform type.

Example:

>> radio_platform_list = radio_platform_t()
>> current_NIC_list_string = control_engine.radio.iface("wlan0").get_radio_platforms()
>> current_NIC_list.platform_info =  current_NIC_list_string[0]
>> current_NIC_list.platform =  current_NIC_list_string[1]

Returns:

current_NIC_list:

a list of pair value, the first value is the interface identifier and the second is the supported platforms.

wishful_upis.radio.get_radio_info(platform_id)

Gets the radio capabilities of a given network card radio_platform_t in terms of supported measurement and supported parameter and list of supported radio program. The information elements used by the UPI_R interface, to manage parameters, measurements and radio program, are organized into data structures, which provide information on the platform type and radio capabilities. When executed, this function return information about available radio capabilities (measurements and parameters) of each interface (radio_platform_t) on the available radio programs (radio_prg_t) available for transmissions over the radio interface.

Example:

>> current_platform_info = radio_info_t()
>> current_platform_info_str = control_engine.radio.iface("wlan0").getRadioInfo(platform_id)
>> current_platform_info.platform_info.platform_id = current_platform_info_str['radio_info'][0]
>> current_platform_info.platform_info.platform = current_platform_info_str['radio_info'][1]
>> current_platform_info.monitor_list = current_platform_info_str['monitor_list']
>> current_platform_info.param_list = current_platform_info_str['param_list']
>> current_platform_info.execution_engine_list_name = current_platform_info_str['exec_engine_list_name']
>> current_platform_info.execution_engine_list_pointer = current_platform_info_str['exec_engine_list_pointer']
>> current_platform_info.radio_program_list_name = current_platform_info_str['radio_prg_list_name']
>> current_platform_info.radio_program_list_path = current_platform_info_str['radio_prg_list_pointer']

Args:

interface:

network interfaces to use

:Returns

result:

return a list in term of a dictionary data type (list of key: value). in which are present the key showed below: ‘radio_info’ –> a list of pair value, the first value is the interface identifier and the second is the supported platforms. ‘monitor_list’ –> a list of supported measurements between the attribute of the class UPI_R ‘param_list’ –> a list of supported Parameters between the attribute of the class UPI_R ‘exec_engine_list_name’ –> a list of supported execution environment name ‘exec_engine_list_pointer’ –> a list of supported execution environment path ‘radio_prg_list_name’–> a list of supported radio program name ‘radio_prg_list_pointer’ –> a list of supported radio program path

wishful_upis.radio.set_rxchannel(freq_Hz, bandwidth)

Set the operating reception frequency or channel.

A value below 1000 indicates a channel number, a value greater than 1000 is a frequency in Hz. It is possible to use the suffix k, M or G to the value (“2.42G” for 2.42 GHz frequency). Channels are usually numbered starting at 1, it is possible to use get_rxchannel() UPI to get the total number of channels, list the available frequencies, and display the current channel.

Example :

>> control_engine.blocking(False).radio.iface("lowpan0").set_rxchannel(26)
>> print(control_engine.blocking(False).radio.iface("lowpan0").get_rxchannel())
26 channels in total; available frequencies :
...
Channel 01 : 904 MHz
Channel 02 : 906 MHz
Channel 03 : 908 MHz
...
Channel 25 : 2.478 GHz
Channel 26 : 2.483 GHz
Current Frequency:2.483 GHz (Channel 26)

Args :

freq_Hz(int): frequency in Hz or channel number bandwidth(int): bandwidth in Hz

Returns:

int:

• 0 if the call was successfully performed
• 1 partial success
• 2 error.

wishful_upis.radio.get_rxchannel()

Return the list of available frequencies in the device and the number of defined channels for the reception module.

Also return the current frequency/channel setted.

Example :

>> print(control_engine.blocking(False).radio.iface("lowpan0").get_rxchannel())
26 channels in total; available frequencies :
...
Channel 01 : 904 MHz
Channel 02 : 906 MHz
Channel 03 : 908 MHz
...
Channel 25 : 2.478 GHz
Channel 26 : 2.483 GHz
Current Frequency:2.483 GHz (Channel 26)

Returns:

list: list of available frequencies/channels and current frequency/channel setted

wishful_upis.radio.set_txchannel(freq_Hz, bandwidth)

Set the operating transmission frequency or channel.

A value below 1000 indicates a channel number, a value greater than 1000 is a frequency in Hz. It is possible to use the suffix k, M or G to the value (“2.42G” for 2.42 GHz frequency). Channels are usually numbered starting at 1, it is possible to use get_rxchannel() UPI to get the total number of channels, list the available frequencies, and display the current channel.

Example :

>> control_engine.blocking(False).radio.iface("lowpan0").set_txchannel(26)
>> print(control_engine.blocking(False).radio.iface("lowpan0").get_txchannel())
26 channels in total; available frequencies :
...
Channel 01 : 904 MHz
Channel 02 : 906 MHz
Channel 03 : 908 MHz
...
Channel 25 : 2.478 GHz
Channel 26 : 2.483 GHz
Current Frequency:2.483 GHz (Channel 26)

Args :

freq_Hz(int): frequency in Hz or channel number bandwidth(int): bandwidth in Hz

Returns:

int:

• 0 if the call was successfully performed
• 1 partial success
• 2 error.

wishful_upis.radio.get_txchannel()

Return the list of available frequencies in the device and the number of defined channels for the transmission module.

Also return the current frequency/channel setted.

Example :

>> print(control_engine.blocking(False).radio.iface("lowpan0").get_rxchannel())
26 channels in total; available frequencies :
...
Channel 01 : 904 MHz
Channel 02 : 906 MHz
Channel 03 : 908 MHz
...
Channel 25 : 2.478 GHz
Channel 26 : 2.483 GHz
Current Frequency:2.483 GHz (Channel 26)

Returns:

list: list of available frequencies/channels and current frequency/channel setted

wishful_upis.radio.get_hwaddr()

Return the Hardware address of the device

Example :

>> mac_address = control_engine.blocking(False).radio.iface("lowpan0").get_hwaddr()
>> print(mac_address)
10:1f:74:54:62:f7

Returns:

String: HW address in the IEEE: MAC-48 format

“Network OS” helpers

The functions supported offer a kind of “Network OS” functionality making it easy for the user to get network wide information regarding communication and interference range for all nodes in the network as well as link parameters for all links present. These helpers are of course based on the basic UPIs offered from UPI_N and UPI_R.

wishful_upis.net_func.estimate_nodes_in_carrier_sensing_range(nodes, interface, **kwargs)

Estimate which nodes are in carrier sensing range using UPIs.

For a network with N nodes all combinations are evaluated, i.e. N over 2.

Note:

make sure that all nodes are time synchronized.

Returns:

list of tuples: In form of (node1, node2, True/False), where True/False if nodes are in carrier sensing range

wishful_upis.net_func.is_in_carrier_sensing_range(node1, node2, interface, **kwargs)

Estimate whether two nodes are in carrier sensing range or not.

Note:

it is implemented differently on different platforms

wishful_upis.net_func.estimate_nodes_in_communication_range(self, nodes, interface, **kwargs)

Estimate which nodes are in communication range using UPIs.

For a network with N nodes all combinations are evaluated, i.e. N over 2.

Note:

make sure that all nodes are time synchronized.

Returns:

list of tuples: In form of (node1, node2, True/False), where True/False if nodes are in communication range

wishful_upis.net_func.is_in_communication_range(node1, node2, interface, **kwargs)

Estimate whether two nodes are in communication range or not.

Subpackages

• WSN specific functions
  • Submodules
  • Network fucntions
  • Radio fucntions
  • “Network OS” helpers
• LTE specific functions
  • Submodules
  • Network fucntions
  • Radio fucntions
  • “Network OS” helpers
• WiFi specific functions
  • Submodules
  • Network fucntions
  • Radio functions
  • “Network OS” helpers