Statistics
| Branch: | Revision:

wishful_upis / wishful_upis / radio.py @ 97a7aedb

History | View | Annotate | Download (22.6 KB)

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

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

8
All protocol-dependent functions are defined in separate folder,
9
e.g. ``wifi/``, ``lowpan/`` or ``lte/``.
10
"""
11
from .lte.radio import *
12
from .wifi.radio import *
13
from .lowpan.radio import *
14

    
15

    
16
__author__ = "Piotr Gawlowicz, Mikolaj Chwalisz, Anatolij Zubow, Peter Ruckebusch, Domenico Garlisi"
17
__copyright__ = "Copyright (c) 2016, Technische Universitat Berlin, iMinds, CNIT"
18
__version__ = "0.1.0"
19
__email__ = "{gawlowicz, chwalisz, zubow}@tkn.tu-berlin.de, peter.ruckebusch@intec.ugent.be, domenico.garlisi@cnit.it"
20

    
21
PARAMETERS = [
22
    "TX_POWER",
23
    "RX_CHANNEL"
24
]
25

    
26

    
27
class Attribute():
28
    def __init__(self, name, data_type, is_read_only):
29
        self.name = name
30
        self.data_type = data_type
31
        self.is_read_only = is_read_only
32

    
33
    def __str__(self):
34
        return ""
35

    
36

    
37
class dot80211(object):
38

    
39
    def __init__(self):
40
        """ This attribute allows to configure the minimum contention window used by CSMA in 802.11"""
41
        self.dot80211_mac_random_access_csma_cwmin = Attribute("dot80211_mac_random_access_csma_cwmin", int, False)
42
        """ This attribute allows to configure the minimum contention window used by CSMA in 802.11"""
43

    
44

    
45
# Generic API to control the lower layers, i.e. key-value configuration.
46
def set_parameters(param_key_values_dict):
47
    """The UPI_R interface is able to configure the radio and MAC behavior by changing parameters.
48
    Parameters correspond to the configuration registers of the hardware platform and to the variables used in
49
    the radio programs. This function (re)set the value(s) of the parameters specified in
50
    the dictionary argument. The list of available parameters supported by all platforms are defined in this module.
51
    Parameters specific to a subgroup of platforms are defined in the corresponding submodules.
52
    A list of supported parameters can be dynamically obtained using the get_radio_info function.
53

54
    Example:
55
        .. code-block:: python
56

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

62
    Args:
63
        param_key_values_dict (dict): dictionary containing the key (string) value (any) pairs for each parameter.
64
            An example is {CSMA_CW : 15, CSMA_CW_MIN : 15, CSMA_CW_MAX : 15}
65

66
    Returns:
67
        dict: A dictionary containing key (string name) error (0 = success, 1=fail, +1=error code) pairs for each parameter.
68
    """
69
    return
70

    
71

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

80
    Example:
81
        .. code-block:: python
82

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

88
    Args:
89
        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].
90

91
    Returns:
92
        dict: A dictionary containing key (string name) and values of the requested parameters.
93
     """
94
    return
95

    
96

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

106
    Example:
107
        .. code-block:: python
108

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

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

117
    Returns:
118
        dict: A dictionary containing key (string name) and values of the requested measurements.
119
    """
120
    return
121

    
122

    
123
def get_measurements_periodic(measurement_key_list, collect_period, report_period, num_iterations, report_callback):
124
    """The UPI_R interface is able to get the radio measurements in a pull based manner periodically.
125
    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.
126
    The function gets the measurements every collect_period and stores them on node memory. Every report_period all measurements are reported to the controller.
127
    This operation is performed a number of times specified by num_iterations. A callback function is used to receive the measurements results.
128
    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.
129
    A list of supported measurements can be dynamically obtained using the get_radio_info function.
130

131
    Example:
132
        .. code-block:: python
133

134
            >> def my_cb(report):
135
            >>     for key in report.keys():
136
            >>         for measurement in report[key]:
137
            >>             print measurement
138
            >> measurement_keys = [NUM_FREEZING_COUNT, TX_ACTIVITY]
139
            >> result = control_engine.radio.iface("wlan0").get_measurements_periodic(measurement_keys,1000000,5000000,10,my_cb)
140
            >> print result
141
            {UPI_RN.NUM_FREEZING_COUNT : 150}
142

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

150
    Returns:
151
        int:
152
            - 0 if the parameter setting call was successfully performed
153
            - 1 partial success
154
            - 2 error.
155
    """
156
    return
157

    
158

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

167
    Example:
168
        .. code-block:: python
169

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

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

180
    Returns:
181
        dict: A dictionary containing an error code for each event.
182
    """
183
    return
184

    
185
# Activation and deactivation of radio programs.
186

    
187

    
188
def activate_radio_program(name):
189
    """This function activates the specified radio program.
190
    When executed, this function stops the current radio program and enables the execution of the radio program specified in the parameter name.
191

192
    Example:
193
        .. code-block:: python
194

195
           >> result = control_engine.radio.iface("wlan0").activate_radio_program("CSMA")
196
           >> print result
197
           0
198

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

202
    Returns:
203
        int:
204
            - 0 if the parameter setting call was successfully performed
205
            - 1 partial success
206
            - 2 error.
207
    """
208
    return
209

    
210

    
211
def deactivate_radio_program(name):
212
    """When executed, this function stops the radio program specified in the parameter radio_program_name.
213

214
    Example:
215
        .. code-block:: python
216

217
           >> result = control_engine.radio.iface("wlan0").deactivate_radio_program("CSMA")
218
           >> print result
219
           0
220

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

224
    Returns:
225
        int:
226
            - 0 if the parameter setting call was successfully performed
227
            - 1 partial success
228
            - 2 error.
229
    """
230
    return
231

    
232

    
233
def get_running_radio_program():
234
    """Returns active radio program.
235

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

239
    Example:
240
        .. code-block:: python
241

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

247
    Args:
248
        myargs:
249
            a dictionary data type (key: value) where the keys are:
250
            The key "interface" specify the network interface to use.
251

252
    Returns:
253
        the name of the active radio program
254
    """
255
    return
256

    
257
''' Transmission of radio waveform (no MAC) '''
258

    
259

    
260
def play_waveform(iface, freq, power_lvl, **kwargs):
261
    """Starts transmitting a radio waveform on signal generator
262

263
    Example:
264
        .. code-block:: python
265

266
            >> iface = '192.168.200.35'
267
            >> freq = '5200'
268
            >> power_lvl = 0
269
            >> controller.radio.play_waveform(iface, freq, power_lvl)
270

271
    Args:
272
        iface (String): Address ip of the interface connected with the signal generator.
273
        freq (int): Frequency of the generated waveform.
274
        power_lvl (int): power level of the generated waveform.
275
        kwargs: Extra argumentes for the signal generator.
276

277
    Returns:
278
        int:
279
            - 0 if the  call was successfully performed
280
            - 1 partial success
281
            - 2 error.
282
    """
283
    return
284

    
285

    
286
def stop_waveform(iface, **kwargs):
287
    """Stops the radio waveform transmitting on signal generator
288

289
    Example:
290
        .. code-block:: python
291

292
            >> iface = '192.168.200.35'
293
            >> controller.radio.stop_waveform(iface)
294

295
    Args:
296
        iface (String): Address ip of the interface connected with the signal generator.
297
        kwargs: Extra argumentes for the signal generator.
298

299
    Returns:
300
        int:
301
            - 0 if the  call was successfully performed
302
            - 1 partial success
303
            - 2 error.
304
    """
305
    return
306

    
307

    
308
def set_tx_power(power_dBm):
309
    """ Sets the transmit power in dBm. If W is the power in Watt, the power in dBm is P = 30 + 10.log(W).
310

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

313
    Example:
314
        .. code-block:: python
315

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

318
    Args:
319
        power_dBm (String): Specify transmit power level in dBm and setting type
320

321
    Returns:
322
        int:
323
            - 0 if the  call was successfully performed
324
            - 1 partial success
325
            - 2 error.
326
    """
327
    return
328

    
329

    
330
def get_tx_power():
331
    """ Gets the current transmit power and the list of various Transmit Powers available on the device
332

333
    Example:
334
        .. code-block:: python
335

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

341
    Returns:
342
        dictionary: transmission power values in dBm
343

344
    """
345
    return
346

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

351
    Example:
352
        .. code-block:: python
353

354
            >> noise_information = controller.radio.get_noise()
355
            >> print(noise_information)
356
            -80dBm
357

358
    Returns:
359
        int: noise level value
360

361
    """
362
    return
363

    
364

    
365
def start_csi_measurements(callback):
366
    """ Start the thread to receive the channel state information. (amplitude + phase)
367

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

372
    Args:
373
        callback (function): Specify the function to call when CSI information have been reported
374

375
    Returns:
376
        int:
377
            - 0 if the  call was successfully performed
378
            - 1 partial success
379
            - 2 error.
380

381
    """
382
    return
383

    
384

    
385
def stop_csi_measurements():
386
    """Stop the thread to receive the channel state information. (amplitude + phase)
387

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

392
    Returns:
393
        int:
394
            - 0 if the  call was successfully performed
395
            - 1 partial success
396
            - 2 error.
397

398
    """
399
    return
400

    
401

    
402
def get_radio_platforms():
403
    """ Gets available radio platforms. The information elements used by the UPI_R
404
    interface, to manage parameters, measurements and radio program, are organized into data structures,
405
    which provide information on the platform type and radio capabilities.
406
    When executed, this function return information about available interfaces on node, the name or the identifier
407
    of the interface and the supported platform type.
408

409
    Example:
410
        .. code-block:: python
411

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

417
    Returns:
418
        current_NIC_list:
419
            a list of pair value, the first value is the interface identifier and the second is the supported platforms.
420
    """
421
    return
422

    
423

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

432
    Example:
433
        .. code-block:: python
434

435
            >> current_platform_info = radio_info_t()
436
            >> current_platform_info_str = control_engine.radio.iface("wlan0").getRadioInfo(platform_id)
437
            >> current_platform_info.platform_info.platform_id = current_platform_info_str['radio_info'][0]
438
            >> current_platform_info.platform_info.platform = current_platform_info_str['radio_info'][1]
439
            >> current_platform_info.monitor_list = current_platform_info_str['monitor_list']
440
            >> current_platform_info.param_list = current_platform_info_str['param_list']
441
            >> current_platform_info.execution_engine_list_name = current_platform_info_str['exec_engine_list_name']
442
            >> current_platform_info.execution_engine_list_pointer = current_platform_info_str['exec_engine_list_pointer']
443
            >> current_platform_info.radio_program_list_name = current_platform_info_str['radio_prg_list_name']
444
            >> current_platform_info.radio_program_list_path = current_platform_info_str['radio_prg_list_pointer']
445

446

447
    Args:
448
     interface:
449
        network interfaces to use
450

451
    :Returns
452
        result:
453
            return a list in term of a dictionary data type (list of key: value). in which are present the key showed below:
454
            'radio_info' --> a list of pair value, the first value is the interface identifier and the second is the supported platforms.
455
            'monitor_list' --> a list of supported measurements between the attribute of the class UPI_R
456
            'param_list' --> a list of supported Parameters between the attribute of the class UPI_R
457
            'exec_engine_list_name' --> a list of supported execution environment name
458
            'exec_engine_list_pointer' --> a list of supported execution environment path
459
            'radio_prg_list_name'--> a list of supported radio program name
460
            'radio_prg_list_pointer' --> a list of supported radio program path
461
    """
462
    return
463

    
464

    
465
def set_rxchannel(freq_Hz, bandwidth):
466
    """Set the operating reception frequency or channel.
467

468
    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
469
    ("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,
470
    list the available frequencies, and display the current channel.
471

472
    Example :
473
        .. code-block:: python
474

475
            >> control_engine.blocking(False).radio.iface("lowpan0").set_rxchannel(26)
476
            >> print(control_engine.blocking(False).radio.iface("lowpan0").get_rxchannel())
477
            26 channels in total; available frequencies :
478
            ...
479
            Channel 01 : 904 MHz
480
            Channel 02 : 906 MHz
481
            Channel 03 : 908 MHz
482
            ...
483
            Channel 25 : 2.478 GHz
484
            Channel 26 : 2.483 GHz
485
            Current Frequency:2.483 GHz (Channel 26)
486

487
    Args :
488
        freq_Hz(int): frequency in Hz or channel number
489
        bandwidth(int): bandwidth in Hz
490

491
    Returns:
492
        int:
493
            - 0 if the  call was successfully performed
494
            - 1 partial success
495
            - 2 error.
496
    """
497
    return
498

    
499

    
500
def get_rxchannel():
501
    """Return the list of available frequencies in the device and the number of defined channels for the reception module.
502
     Also return the current frequency/channel setted.
503

504
    Example :
505
        .. code-block:: python
506

507
            >> print(control_engine.blocking(False).radio.iface("lowpan0").get_rxchannel())
508
            26 channels in total; available frequencies :
509
            ...
510
            Channel 01 : 904 MHz
511
            Channel 02 : 906 MHz
512
            Channel 03 : 908 MHz
513
            ...
514
            Channel 25 : 2.478 GHz
515
            Channel 26 : 2.483 GHz
516
            Current Frequency:2.483 GHz (Channel 26)
517

518
    Returns:
519
        list: list of available frequencies/channels and current frequency/channel setted
520
    """
521
    return
522

    
523

    
524
def set_txchannel(freq_Hz, bandwidth):
525
    """Set the operating transmission frequency or channel.
526

527
    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
528
    ("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,
529
    list the available frequencies, and display the current channel.
530

531
    Example :
532
        .. code-block:: python
533

534
            >> control_engine.blocking(False).radio.iface("lowpan0").set_txchannel(26)
535
            >> print(control_engine.blocking(False).radio.iface("lowpan0").get_txchannel())
536
            26 channels in total; available frequencies :
537
            ...
538
            Channel 01 : 904 MHz
539
            Channel 02 : 906 MHz
540
            Channel 03 : 908 MHz
541
            ...
542
            Channel 25 : 2.478 GHz
543
            Channel 26 : 2.483 GHz
544
            Current Frequency:2.483 GHz (Channel 26)
545

546
    Args :
547
        freq_Hz(int): frequency in Hz or channel number
548
        bandwidth(int): bandwidth in Hz
549

550
    Returns:
551
        int:
552
            - 0 if the  call was successfully performed
553
            - 1 partial success
554
            - 2 error.
555
    """
556
    pass
557

    
558

    
559
def get_txchannel():
560
    """ Return the list of available frequencies in the device and the number of defined channels for the transmission module.
561
     Also return the current frequency/channel setted.
562

563
    Example :
564
        .. code-block:: python
565

566
            >> print(control_engine.blocking(False).radio.iface("lowpan0").get_rxchannel())
567
            26 channels in total; available frequencies :
568
            ...
569
            Channel 01 : 904 MHz
570
            Channel 02 : 906 MHz
571
            Channel 03 : 908 MHz
572
            ...
573
            Channel 25 : 2.478 GHz
574
            Channel 26 : 2.483 GHz
575
            Current Frequency:2.483 GHz (Channel 26)
576

577
    Returns:
578
        list: list of available frequencies/channels and current frequency/channel setted
579

580
    """
581
    return
582

    
583

    
584
def get_hwaddr():
585
    """ Return the Hardware address of the device
586

587
    Example :
588
        .. code-block:: python
589

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

594
    Returns:
595
        String: HW address in the IEEE: MAC-48 format
596
    """
597
    return