Cortexlab users do not have direct access to the cortexlab radio nodes. They have to package their experiment in a minus scenario and launch it from the frontend (airlock).

This is simple as long as the scenario is made, for example, from simple python scripts or static binaries, using the right version of libraries and/or gnuradio than installed on the nodes. But things get more complex as soon as users want to make use of:

1. gnuradio version different from the version on the nodes
2. binaries relying on shared libraries which are not installed on the cortexlab nodes (uncommon libraries or custom libraries)
3. binaries relying on versions of shared libraries which are not present on on the cortexlab nodes (perhaps because the binaries where compiled on a different operating system, or a different version of the same operating system.
4. gnuradio “Out Of Tree” (OOT) modules, that is, custom gnuradio components (blocks, and possibly associated gnuradio-companion block metadata) which are not install on the cortexlab nodes. These OOT modules may rely themselves on other gnuradio version, custom binaries or libraries not installed on the nodes, or with the wrong version, such as in (1), (2), (3).

There are a few ways to tackle these problems.

There is basically no way to avoid this issue: users need to target the same gnuradio version than the one on the cortexlab nodes.

Actually this is not only about gnuradio, but about the whole package of software used to run the radio on the nodes. We refer to this package as the cortexlab toolchain. It is made of:

• gnuradio
• some gnuradio additional modules / blocks, such as blocks which interface with the radio hardware (uhd for usrp and similar blocks to interface with picosdr nodes)
• some gnuradio additional modules adding convenient tools, which we decided to incude, such as gr-iqbal.
• software for supporting the picosdr: xilinx ise, digilent hs2 (the jtag used on the cortexlab nodes) and adp from nutaq.

There is currently three possibilities for working with the same version of toolchain than the one on the cortexlab nodes:

• use the cortexlab toolchain which is installed on the airlock frontend. It is the exact same toolchain as on the nodes, the only difference is that there is no hardware (usrp, picosdr, jtag) connected to the frontend.
• build a cortexlab toolchain on a user's workstation. We provide the cxlb-build-toolchain tool, which is the tool that we use to build the toolchain on the nodes. This tool is limited to 64 bit linux and is tested only under debian. For each toolchain built with this tool, a bundle file is written in the toolchain directory, which tracks all exact versions of all packages included in the toolchain. The bundle file for the current cortexlab toolchain can be found on airlock in /cortexlab/toolchains/current/share/cxlb-build-toolchain/build.bundle. This file can be used as input to cxlb-build-toolchain to be sure to build the exact same toolchain. cxlb-build-toolchain also provides options to select which parts of the toolchain to build. For example, a user willing to experiment only on usrp won't need to include the picosdr specific stuff.
• build the same version of gnuradio than on airlock, without using our cxlb-build-toolchain script. In this case, users are on their own. In the majority of situation this should cause no issue but there may be some slight incompatibilities with the toolchain on the nodes in some rare situations.

Besides, the main advantage of the cxlb-build-toolchain is that it takes care to install everything in a given directory, as regular user. It then generates and installs two scripts, one that has to be run by root, to configure the dynamic loader and udev to use the toolchain, the other that has to be sourced by the user which will use the toolchain, to configure the environment. Thus:

• it is possible to have more than one toolchain installed in parallel. You only need to re-run the root script to switch to a different toolchain, and reboot (or possibly restart udev), and re-source the environment configuration script.
• you are sure that it does not conflict with anything in the regular directory tree structure of your system. In particular, it cannot conflit with the debian package system.
• everything from the toolchain is kept separated in the toolchain directory

The gnuradio build system is designed to allow building OOT gnuradio modules easily. For this, users need to use gr_modtool to create their module.