This project is an adaptation of the gr_ephyl project, creating a slotted and uplink framework to work on PHY or MAC layer.
To install the slotted framework (GNURadio3.7) you must run the following command :
git clone https://github.com/AmauryPARIS/gr-ephyl.git
cd gr-ephyl/
mkdir build && cd build
cmake -DCMAKE_INSTALL_PREFIX=/cortexlab/toolchains/current ..
make install
If you want to run the framework within the FIT/CorteXlab testbed, you should install the project within this provided docker image
docker pull m1mbert/cxlb-gnuradio-3.7
docker run -dti --net=host --expose 2222 --privileged m1mbert/cxlb-gnuradio-3.7:1.0
This will enable the usage of the main OOT blocks of the ephyl/s3cap project. If you want to use the available LoRa PHY layer (based on this project), you also need to install it. You can follow the installation step (don't forget to source setpaths.sh
).
For an easier "plug and play" solution, you can use this docker image where both EPHYL/S3CAP and LoRa are installed.
Depending on the flowgraph you would like to use, generating the python executable of the needed hierarchical block will be required.
This project offers a slotted and uplink transmission from multiple nodes to a base station. For each frame, the access policy of the MAC layer will set packets to be transmitted on chosen slots, and control messages. Then the PHY layer will generate and transmit all needed signals during the slotted time frame, to be finally received by the base station. Both nodes and the base station use the results of the previous frame to decide their next actions.
The S3CAP framework provides easy implementation of MAC layers. Exemples are provided in the (poorly named) upper
folder.
upper_class.py
is a set of function to exchange information and instruction between your MAC layer (yours to implement) and the PHY layer (inside the GNU Radio environment)sn_upper.py
is a dummy MAC layer for each sensor to set transmission of packets on the slotted uplink channel and control messagesbs_upper.py
is also a dummy MAC layer for the base station to set control messages
You can implement your own MAC layer by using the upper_class
, as it is presented in sn_upper.py
and bs_upper.py
. The MAC layer will work regardless of the used PHY layer (LoRa and NB IoT are provided, but you can also use your own project -- see below)
Two LoRa and NBIoT PHY layers are provided in this project. If you are only working on MAC, the nature of the PHY layer might not be of any interest to you and you should feel free to use LoRa, as presented below. However if you want to use another PHY layer, this is doable.
The framework is built so that the signal to be transmitted by a node is generated in advance and stored in the OOT block sn_scheduler.py
. To implement a new PHY layer within the framework, you need to :
- Replace the
LoRa TX chain
hier block with your own PHY layer in thehier_sn_lora.grc
flowgraph - Update the
stream_to_tagged_stream
packet length parameter in thehier_sn_lora.grc
flowgraph and thehandle_msg
function in the OOT blocksn_scheduler.py
to compute the length of your generated signal, so that it can be stored before being send - Replace the
LoRa RX chain
hier block with your own PHY layer in thehier_bs_lora.grc
flowgraph
If you want to run the project on your local computer, use "demo_local_lora.grc" to get started. In this exemple flowgraph you will find two LoRa nodes transmitting at a base station in the slotted environment of the S3CAP framework. This is the PHY layer and with it we need a MAC layer to set packets and control messages (sn_upper.py
and bs_upper.py
). Thereefor, to run this exemple, you should run, in this order and in separate terminals, the following commands :
$ python PATH_TO/gr-ephyl/upper/bs_upper.py
$ python PATH_TO/gr-ephyl/upper/bs_upper.py
$ python PATH_TO/gr-ephyl/examples/LoRa/demo_loop_lora.py
To run the project in the FIT/CorteXlab testbed, you should first follow some tutorials to get familiar with its environment. After that, you can run a dummy scenario with two transmitting nodes and a base station.
- On
NODE_X
- the first sensor
python2 /root/cxlb_toolchain_build/gr-ephyl/upper/sn_upper.py --slot_count=4 &
python2 /root/cxlb_toolchain_build/gr-ephyl/examples/LoRa/sn_multislot_dyn_ephyl_lora.py --sn-id=A --ip-bs-addr=NODE_Z --S=4
- On
NODE_Y
- the second sensor
python2 /root/cxlb_toolchain_build/gr-ephyl/upper/sn_upper.py --slot_count=4 &
python2 /root/cxlb_toolchain_build/gr-ephyl/examples/LoRa/sn_multislot_dyn_ephyl_lora.py --sn-id=B --ip-bs-addr=NODE_Z --S=4
- On
NODE_Z
- the base station
python2 /root/cxlb_toolchain_build/gr-ephyl/upper/bs_upper.py --slot_count=4 &
python2 /root/cxlb_toolchain_build/gr-ephyl/examples/LoRa/bs_multisn_multislot_dyn_ephyl_lora.py --sn-1-ip-addr=NODE_X --sn-2-ip-addr=NODE_Y --S=4
Detailed documentation is available in the documentation folder
and here
A tutorial is available on the FIT/CorteXlab wiki page, here.
If you get the ImportError: No module named lora_sdr
error, you should update and run the following command. You can also add it to your .bashrc
for a more permanent setup.
source PATH_TO/LoRa_PHY_Cxlb/gr-lora_sdr/apps/setpaths.sh
The synchronization precision could be improved by using the rx_time
tag in reception to compute the sample count for each time slot.