## BLE Phy for BabbleSim

The overall
[BabbleSim documentation](https://babblesim.github.io/)
provides information about
[BabbleSim's architecture](https://babblesim.github.io/architecture.html),
as well as
[general information on this physical layer](https://babblesim.github.io/2G4.html).

There you can also find some
[simple usage examples](https://babblesim.github.io/example_2g4.html).

This Phy accepts many command line parameters, for more information about these,
you can run it with the `--help` option.

For more details about the design of this Phy please check
[README_design.md](./README_design.md).

For information about how to select a different channel or modem model
[check this page](https://babblesim.github.io/2G4_select_ch_mo.html).
For information about how to implement a new channel or modem model,
check [README_channel_and_modem_if.md](README_channel_and_modem_if.md)

The interface between the simulated devices and this Phy is provided by
[ext_2G4_libPhyComv1](https://github.com/BabbleSim/ext_2G4_libPhyComv1).
Please refer to
[its documentation](https://github.com/BabbleSim/ext_2G4_libPhyComv1/blob/master/docs/README.md)
for more information about the exact protocol and the messages which each device
exchanges with this Phy.

### A few notes about the device-Phy interface
A device is free to advance its simulated time even before it gets
a response to a request and to pipe several consecutive requests.
This can be done easily and safely for Tx and Wait requests.
It would be more difficult though for a device to be able to
pipe any request after a Rx, RSSI, or CCA attempt.<br>
But this Phy follows the principle of not responding to a request until the
time in which that request would have been completed.

Note that piping several requests ahead of time will greatly increase the
speed of the simulation if there is free CPU cores.
Even if there is no free CPUs, it will overall increase performance by
decreasing the number of required context switches.

## Channels and modems

To be able to emulate the system performance in different environments, with
different modems and analog components, and with different tradeoffs of
simulation speed and accuracy, this Phy allows to use exchangable channel
and modem models.
How a user selects then is described in
[this page](https://babblesim.github.io/2G4_select_ch_mo.html)

All a channel needs to do for this Phy to be able to load and use it is to
implement the interface described in [channel_if.h](../src/channel_if.h)

Similarly modems models would need to implement the interface described in
[modem_if.h](../src/modem_if.h)

## Overall internal design

In short this Phy is composed of the following main components:

* A list of current (and future) transmissions in the air
* For each device interface: A state machine where transitions/operations
  can either be done immediately or be scheduled for a future time
* A list of (timed) events (function queue)

### The pending transmissions list

The pending list of transmissions (Tx list,
[pending_tx_list.c](../src/p2G4_pending_tx_list.c)/
[h](../src/p2G4_pending_tx_rx_list.h))
is an array with one entry per device (`tx_l_c_t`).
Where each element keeps a current or future transmission parameters,
as well as an indication of the transmission being currently active.<br>
An interface is provided to modify (register) and entry, set it to active,
and clear it.<br>

### Functions queue

The list of events/function queue,
([func_queue.h](../src/p2G4_func_queue.h),
[funcqueue.c](../src/p2G4_func_queue.c))
is used by each of the device interfaces to schedule future operations.
This queue has one entry per interface, which consists just of a function to be
called and the simulated time when the call should be done.<br>

This queue provides functions to modify (add) an entry, to remove it,
as well as to get the time of the next event.<br>
Each time a new event is queued the list finds which is the next event
which needs to be executed. The queue is ordered first by time, and then by
event type (`f_index_t`).<br>
You can see more details in [p2G4_func_queue.h](../src/p2G4_func_queue.h).

### Device interface state machine

Each device interface implements the same state machine, which in short works
as follows:

1. The next operation is requested from the device.
   Depending on what the operation is, either one of the substatemachines events
   is started (Rx, Tx, Wait, RSSI, CCA), or the device interface is disabled
   (DISCONNECT), or the whole simulation is ended (TERMINATE)
2. The substate machine transitions over time (using the function queue)
   until it eventually comes back to 1.

You can find more details about each substate machine in
[README_device_interface.md](README_device_interface.md)

## Overall workings

The Phy starts by parsing the command line parameters, intializing all its
components, and loading and initializing the channel and modem libraries.

Then it will block until receiving the next request from each device.

Note that this is the basic way of working of the Phy:
It cannot let time pass until it knows what is it that all devices want to do.
It cannot know if a reception will be succesfull until it knows what all others
devices will be doing during that reception time.

Once it knows what it is that all devices want to do, it can let time pass
until it handles the first (earliest) device needs, and then it must wait until
that device requests what it wants next.

It will then repeat this process again and again, until the simulation end time
has been reached, or all devices have disconnected.

[Device interface activity diagrams](Device_interface.svg)

![Device interfacec activity diagrams (for GitHub web rendering)](https://raw.githubusercontent.com/BabbleSim/ext_2G4_phy_v1/master/docs/Device_interface.svg?sanitize=true)
<!--The ?sanitize=true is an ugly thing for GitHub to enable the svg to be
rendered into the markdown preview-->

Note that a few details are omited from these diagrams for clarity.
Please check [the code](../src/p2G4_main.c) for more details.

## BLE Phy activity dumps

The Physical layer (Phy) can dump all radio activity to files.
These files will contain all transmissions, receptions and RSSI measurements
from each device.

The files are stored in `results/<sim_id>/d_2G4_<dev_number>.{Rx|Tx|RSSI}.csv`

These files are formated as comma separated files (csv) with one line heading,
and, after, one line for each transaction.

This dumps can be converted to other formats other tools can process.
Check the `dump_post_process/` folder for more info.

The Phy can also be run in "check" mode. In this mode it will compare the
content of already existing files (for ex. from a previous run) with what it
would have generated otherwise, and warn when differences are found.
Run the Phy with `--help` to get more info about this option.

### Tx (v1) format

For each device transmission, these are the columns:

* start_time : microsecond when the first bit of the packet in air starts (1st bit of the preamble)
* end_time: microsecond when the last bit of the packet ends (last bit of the CRC). Note that a packet may have been aborted before reaching this point.
* center_freq: As an offset from 2400MHz, in MHz, carrier frequency. Note that frequencies below 0 and above 80 are valid for interferers.
* phy_address : Physical address / sync word of the packet
* modulation: Modulation type. One of P2G4_MOD_* : 0x10 = BLE 1 Mbps, 0x20 = BLE 2Mbps
* power_level: In dBm, transmitted power level (accounting for the device antenna gain)
* abort_time: When was the packet transmission aborted, or TIME_NEVER (2^64-1) if not aborted.
* recheck_time: (internal info) When did the device request to reevaluate the possibility to abort the packet last time
* packet_size: Size of the packet in bytes (not counting preamble or syncword, but counting header, payload, MIC and CRC)
* packet: Actual packet data (packet_size bytes)

### Rx (v1)

For each device reception attempt, these are the columns:

* start_time: When (in air time) was the receiver opened
* scan_duration: For how long was the receiver opened attempting to have a physical address match
* phy_address: Physical address / sync word which was searched for
* modulation: Type of modulation the receiver is configured to receive. One of P2G4_MOD_*
* center_freq: As an offset from 2400MHz, in MHz, carrier frequency.
* antenna_gain: Receiver antenna gain in dB
* sync_threshold: Reception tolerance: How many errors do we accept before considering the preamble + address sync lost
* header_threshold: How many errors do we accept in the header before giving a header error (automatically in the phy).
* pream_and_addr_duration: Duration of the preamble and syncword (for 1Mbps BLE, 40 micros)
* header_duration:  Duration of the packet header (for 1Mbps BLE, 16 micros)
* bps : Phy bitrate in bits per second (for 1Mbps 1e6)
* abort_time: When was the packet reception aborted, or TIME_NEVER (2^64-1) if not aborted.
* recheck_time: (internal info) When did the device request to reevaluate the possibility to abort the reception last time
* tx_nbr: Which simulated device number was synchronized to (-1 if none)
* biterrors: How many bit errors there was during the packet reception
* sync_end: Last micros (included) in which the address ended (only if there was a sync)
* header_end: Last micros (included) in which the packet header ended (only if there was a sync)
* payload_end: Last micros (included) in which the packet (CRC) ended (only if there was a sync)
* rx_time_stamp: Reception time stamp (last microsecond of the sync word/address)
* status: Reception status. One of P2G4_RXSTATUS*: 1:Ok, 2: CRC error, 3: Header Error, 4: No sync
* RSSI: Measured RSSI (Received signal strenght indication) value in dBm
* packet_size: Size of the packet in bytes (not counting preamble or syncword, but counting header, payload, MIC and CRC)
* packet: Actual packet data (packet_size bytes), note that this is the actual transmitted packet, without possible bit errors

### RSSI:

For each RSSI measurement (excluding the ones performed automatically in Rx measurements)

* meas_time: microsecond in which the mesaurement was performed
* modulation: Type of modulation the receiver is configured for during the measurement. One of P2G4_MOD_*
* center_freq: As an offset from 2400MHz, in MHz.
* antenna_gain: Receiver antenna gain in dB
* RSSI: Measured RSSI (Received signal strenght indication) value in dBm

### Tx (v2) format

For each device transmission, these are the columns:

* start_tx_time: microsecond when the transmitter starts emitting
* end_tx_time: microsecond when the transmitter stopped emitting (note that it may have been aborted)
* start_packet_time: microsecond when the first bit of the packet in air would start (assuming it is not truncated) (1st bit of the preamble)
* end_packet_time: microsecond when the last bit of the packet ends (for ex. last bit of the CRC). Note that a packet may have been aborted.
* center_freq: As an offset from 2400MHz, in MHz, carrier frequency. Note that frequencies below 0 and above 80 are valid for interferers.
* phy_address : Physical address / sync word of the packet
* modulation: Modulation type. One of P2G4_MOD_* : 0x10 = BLE 1 Mbps, 0x20 = BLE 2Mbps
* power_level: In dBm, transmitted power level (accounting for the device antenna gain)
* abort_time: When was the packet transmission aborted, or TIME_NEVER (2^64-1) if not aborted.
* recheck_time: (internal info) When did the device request to reevaluate the possibility to abort the packet last time
* packet_size: Size of the packet in bytes (not counting preamble or syncword, but counting header, payload, MIC and CRC)
* packet: Actual packet data (packet_size bytes)

### Rx (v2)

For each device reception attempt, these are the columns:

* start_time: When (in air time) was the receiver opened
* scan_duration: For how long was the receiver opened attempting to have a physical address match
* n_addr: How many addresses is the receiver trying to search for simultaneously
* phy_address[]: Array of physical addresses / sync wordes which were searched for
* modulation: Type of modulation the receiver is configured to receive. One of P2G4_MOD_*
* center_freq: As an offset from 2400MHz, in MHz, carrier frequency.
* antenna_gain: Receiver antenna gain in dB
* acceptable_pre_truncation: Up to how many µs of the preamble may have been missed by the receiver
* sync_threshold: Reception tolerance: How many errors do we accept before considering the preamble + address sync lost
* header_threshold: How many errors do we accept in the header before giving a header error (automatically in the phy).
* pream_and_addr_duration: Duration of the preamble and syncword (for 1Mbps BLE, 40 micros)
* header_duration:  Duration of the packet header (for 1Mbps BLE, 16 micros)
* error_calc_rate : Error calculation rate in bits per second (for ex. for 1Mbps 1e6)
* resp_type: Type of response the receiver wants at the reception end (0 only supported so far)
* abort_time: When was the packet reception aborted, or TIME_NEVER (2^64-1) if not aborted.
* recheck_time: (internal info) When did the device request to reevaluate the possibility to abort the reception last time
* tx_nbr: Which simulated device number was synchronized to (-1 if none)
* matched_addr: Which phy address was actually matched
* biterrors: How many bit errors there was during the packet reception
* sync_end: Last micros (included) in which the address ended (only if there was a sync)
* header_end: Last micros (included) in which the packet header ended (only if there was a sync)
* payload_end: Last micros (included) in which the packet (CRC) ended (only if there was a sync)
* rx_time_stamp: Reception time stamp (last microsecond of the sync word/address)
* status: Reception status. One of P2G4_RXSTATUS*: 1:Ok, 2: CRC/Payload error, 3: Header Error, 4: No sync
* RSSI: Measured RSSI (Received signal strenght indication) value in dBm
* packet_size: Size of the packet in bytes (not counting preamble or syncword, but counting header, payload, MIC and CRC)
* packet: Actual packet data (packet_size bytes), note that this is the actual transmitted packet, without possible bit errors

### CCA

For each device CCA request attempt, these are the columns:

* start_time: When (in air time) was the measurement started
* scan_duration: For how long, in µs, is the measurement performed
* scan_period: How often will the phy re-measure/check
* modulation: Which modulation is being search for, and which modulation is the receiver opened with for the RSSI measurements
* center_freq: Center frequency for the search
* antenna_gain: Receiver antenna gain in dB
* threshold_mod: Power threshold at which the search may stop, while it detects the expected modulation
* threshold_rssi: Power threshold at which the search may stop, when it does not detect the expected modulation
* stop_when_found: Stop when detecting the modulation (and the rx power > threshold_mod) (1), stop when not detecting the modulation (and the rx power > threshold_rssi) (2), or both (3), or neither (0)
* abort_time: When was the measurement aborted, or TIME_NEVER (2^64-1) if not aborted.
* recheck_time: (internal info) When did the device request to reevaluate the possibility to abort last time
* end_time: When did the measurement actually end
* RSSI_ave: Average measured RSSI value (in dBm)
* RSSI_max: Maximum measured RSSI value (in dBm)
* mod_rx_power: Maximum measured power/RSSI when a compatible modulation was heard
* mod_found: Was a compatible modulation heard over its threshold power or not
* rssi_overthreshold: Was the rssi value over its threshold power or not