| 1 | # Using CMake |
| 2 | |
| 3 | @tableofcontents |
| 4 | |
| 5 | <!-- markdownlint-disable MD031 --> |
| 6 | A more modern approach instead of using hand-crafted _Makefiles_ & _configure_ scripts |
| 7 | to build & install software. Please note that these instructions are not needed if you |
| 8 | have already installed the library using [these older instructions](linux_install.md) |
| 9 | |
| 10 | ## Installing the library |
| 11 | |
| 12 | You can install the library in a few different ways. |
| 13 | |
| 14 | - Building and installing the library from source code is preferable since it will include all the latest changes. |
| 15 | - Installing the library (via a package manager) from a pre-built package is mostly for cross-compiling purposes, but it can be useful for environments that don't have all the build-time dependencies (namely CMake). |
| 16 | |
| 17 | @warning If you have previously installed the library from source code using the |
| 18 | [the older instructions](linux_install.md), then you will need to |
| 19 | uninstall it manually to avoid runtime conflicts. |
| 20 | ```shell |
| 21 | sudo rm /usr/local/lib/librf24.* |
| 22 | sudo rm /usr/local/lib/librf24-bcm.so |
| 23 | sudo rm -r /usr/local/include/RF24 |
| 24 | ``` |
| 25 | |
| 26 | The _librf24-bcm.so_ file may not exist if you used CMake to install the library. |
| 27 | |
| 28 | ### Automatic Installation |
| 29 | |
| 30 | There is a newer automatic install script that makes use of the CMake approach. |
| 31 | |
| 32 | 1. Download the install.sh file from [https://github.com/nRF24/.github/blob/main/installer/install.sh](https://github.com/nRF24/.github/blob/main/installer/install.sh) |
| 33 | ```shell |
| 34 | wget https://raw.githubusercontent.com/nRF24/.github/main/installer/install.sh |
| 35 | ``` |
| 36 | 2. Make it executable |
| 37 | ```shell |
| 38 | chmod +x install.sh |
| 39 | ``` |
| 40 | 3. Run it and choose your options |
| 41 | ```shell |
| 42 | ./install.sh |
| 43 | ``` |
| 44 | |
| 45 | @warning |
| 46 | `SPIDEV` is now always selected as the default driver because |
| 47 | all other Linux drivers are being removed in the future. |
| 48 | See [RF24 issue #971](https://github.com/nRF24/RF24/issues/971) for rationale. |
| 49 | |
| 50 | It will also ask to install a python package named [pyRF24](https://github.com/nRF24/pyRF24). |
| 51 | This is not the same as the traditionally provided python wrappers as the pyRF24 package can be |
| 52 | used independent of the C++ installed libraries. For more information on this newer python |
| 53 | package, please check out [the pyRF24 documentation](https://nrf24.github.io/pyRF24/). |
| 54 | 4. Try an example from one of the libraries |
| 55 | ```shell |
| 56 | cd ~/rf24libs/RF24/examples_linux |
| 57 | ``` |
| 58 | |
| 59 | Edit the gettingstarted example, to set your pin configuration |
| 60 | ```shell |
| 61 | nano gettingstarted.cpp |
| 62 | ``` |
| 63 | |
| 64 | Build the examples. Remember to set the `RF24_DRIVER` option according to the one that was |
| 65 | selected during the scripted install. |
| 66 | ```shell |
| 67 | mkdir build && cd build |
| 68 | cmake .. -D RF24_DRIVER=SPIDEV |
| 69 | make |
| 70 | ``` |
| 71 | |
| 72 | Run the example |
| 73 | ```shell |
| 74 | sudo ./gettingstarted |
| 75 | ``` |
| 76 | |
| 77 | ### Building from source code |
| 78 | |
| 79 | 1. Install prerequisites if there are any (PiGPIO, WiringPi, MRAA, LittleWire libraries, and enable the SPI bus(es) in the OS). |
| 80 | |
| 81 | CMake may need to be installed |
| 82 | ```shell |
| 83 | sudo apt-get install cmake |
| 84 | ``` |
| 85 | @note See the [MRAA documentation](http://iotdk.intel.com/docs/master/mraa/index.html) for more information on installing MRAA. |
| 86 | 2. Make a directory to contain the RF24 library and possibly other RF24\* libraries and enter it |
| 87 | ```shell |
| 88 | mkdir ~/rf24libs |
| 89 | cd ~/rf24libs |
| 90 | ``` |
| 91 | 3. Clone the [RF24 repo](https://github.com/nRF24/RF24) and navigate to it |
| 92 | ```shell |
| 93 | git clone https://github.com/nRF24/RF24.git RF24 |
| 94 | cd RF24 |
| 95 | ``` |
| 96 | 4. Create a build directory inside the RF24 directory and navigate to it. |
| 97 | ```shell |
| 98 | mkdir build |
| 99 | cd build |
| 100 | ``` |
| 101 | 5. Configure build environment |
| 102 | |
| 103 | @note When using these instructions to install RF24Mesh, RF24Network, or RF24Gateway, |
| 104 | the following `RF24_DRIVER` option is only needed for the RF24 library and |
| 105 | examples as well as the examples for RF24Network, RF24Mesh, and RF24Gateway. The `RF24_DRIVER` |
| 106 | option is not needed when installing the libraries for RF24Network, RF24Mesh, and RF24Gateway. |
| 107 | |
| 108 | Instead of specifying the `RF24_DRIVER` option in the CLI, it is recommended to use a environment |
| 109 | variable named `RF24_DRIVER`. |
| 110 | |
| 111 | ```shell |
| 112 | export RF24_DRIVER=SPIDEV |
| 113 | ``` |
| 114 | |
| 115 | These instructions assume you have not set an environment variable. |
| 116 | |
| 117 | ```shell |
| 118 | cmake .. -D RF24_DRIVER=SPIDEV |
| 119 | ``` |
| 120 | Instead of using `SPIDEV` driver (recommended), you can also specify the `RPi`, `wiringPi`, |
| 121 | `MRAA`, or `LittleWire` as alternative drivers. |
| 122 | |
| 123 | @warning |
| 124 | `SPIDEV` is now always selected as the default driver because |
| 125 | all other Linux drivers are being removed in the future. |
| 126 | See [RF24 issue #971](https://github.com/nRF24/RF24/issues/971) for rationale. |
| 127 | 6. Build and install the library |
| 128 | ```shell |
| 129 | make |
| 130 | sudo make install |
| 131 | ``` |
| 132 | 7. Build the examples |
| 133 | |
| 134 | Navigate to the _examples_linux_ directory |
| 135 | ```shell |
| 136 | cd ../examples_linux |
| 137 | ``` |
| 138 | Make sure the pins used in the examples match the pins you used to connect the radio module |
| 139 | ```shell |
| 140 | nano gettingstarted.cpp |
| 141 | ``` |
| 142 | and edit the pin numbers as directed in the [linux/RPi general documentation](rpi_general.md). |
| 143 | Create a build directory in the examples_linux directory and navigate to it. |
| 144 | ```shell |
| 145 | mkdir build |
| 146 | cd build |
| 147 | ``` |
| 148 | Now you are ready to build the examples. |
| 149 | ```shell |
| 150 | cmake .. |
| 151 | make |
| 152 | ``` |
| 153 | If using the `MRAA` or `wiringPi` drivers, then you may need to specify the `RF24_DRIVER` |
| 154 | option again. |
| 155 | ```shell |
| 156 | cmake .. -D RF24_DRIVER=wiringPi |
| 157 | make |
| 158 | ``` |
| 159 | |
| 160 | Remember that the `RF24_DRIVER` option is needed for the RF24Network, RF24Mesh, and RF24Gateway |
| 161 | examples if you specified that option (via CLI or environment variable) when installing the |
| 162 | RF24 library and examples. |
| 163 | 8. Run an example file |
| 164 | ```shell |
| 165 | sudo ./gettingstarted |
| 166 | ``` |
| 167 | |
| 168 | ### Using a package manager |
| 169 | |
| 170 | The RF24 library now (as of v1.4.1) has pre-built packages (.deb or .rpm files) that |
| 171 | can be installed on a Raspberry Pi. These packages can be found on the library's |
| 172 | [GitHub release page](https://GitHub.com/nRF24/RF24/releases) |
| 173 | |
| 174 | 1. Download the appropriate package for your machine |
| 175 | |
| 176 | Go to the library's [GitHub release page](https://GitHub.com/nRF24/RF24/releases), and look for |
| 177 | the latest release's assets. |
| 178 | |
| 179 | For all Raspberry Pi variants using the Raspberry Pi OS (aka Raspbian), you need the file marked |
| 180 | for _armhf_ architecture. |
| 181 | |
| 182 | For Raspberry Pi variants using a 64-bit OS (like Ubuntu), you need the file marked for |
| 183 | _arm64_ architecture. |
| 184 | |
| 185 | Notice that the filenames will include the name of the utility driver that the package was built with. |
| 186 | This does not mean that the LittleWire, MRAA, or wiringPi libraries are included in the package (you will still |
| 187 | need to install those yourself beforehand). |
| 188 | 2. Install the downloaded pkg |
| 189 | |
| 190 | If you downloaded the file directly from your target machine using the desktop environment, then |
| 191 | you only need to double-click the package (deb or rpm) file, and the OS should do the rest. |
| 192 | |
| 193 | If you downloaded the file remotely and want to copy it over ssh, then use the `scp` command in a terminal. |
| 194 | ```shell |
| 195 | scp pkg_filename.deb pi@host_name:~/Downloads |
| 196 | ``` |
| 197 | @note You do not need to do this from within an ssh session. Also, you can use the target machine's IP |
| 198 | address instead of its host name. |
| 199 | |
| 200 | The `scp` command will ask you for a password belonging to the user's name on the remote machine (we used |
| 201 | `pi` in the above example). |
| 202 | |
| 203 | Now you can open up a ssh session and install the copied package from the terminal. |
| 204 | ```shell |
| 205 | ssh pi@host_name |
| 206 | cd Downloads |
| 207 | dpkg -i pkg_filename.deb |
| 208 | ``` |
| 209 | |
| 210 | ## Cross-compiling the library |
| 211 | |
| 212 | The RF24 library comes with some pre-made toolchain files (located in the |
| 213 | _RF24/cmake/toolchains_ directory) to use in CMake. To use these toolchain files, |
| 214 | additional command line options are needed when configuring CMake to build the library |
| 215 | (step 5 in the above instructions to build from source). |
| 216 | |
| 217 | ```shell |
| 218 | cmake .. -D CMAKE_TOOLCHAIN_FILE=cmake/toolchains/armhf.cmake |
| 219 | make |
| 220 | ``` |
| 221 | |
| 222 | If you plan on using the cross-compiled library with your personal cross-compiled |
| 223 | project, then it is advised to specify the path that your project will look in when |
| 224 | linking to the RF24 library: |
| 225 | |
| 226 | ```shell |
| 227 | cmake .. -D CMAKE_INSTALL_PREFIX=/usr/arm-linux-gnueabihf -D CMAKE_TOOLCHAIN_FILE=cmake/toolchains/armhf.cmake |
| 228 | make |
| 229 | sudo make install |
| 230 | ``` |
| 231 | |
| 232 | Remember to also specify the `RF24_DRIVER` option (via CLI or environment variable) if |
| 233 | not using the auto-configuration feature (see step 5 in the above instructions to build |
| 234 | from source). |
| 235 | |
| 236 | ### Installing the library remotely |
| 237 | |
| 238 | To install remotely, you can create an installable package file using CMake's built-in |
| 239 | program called CPack. |
| 240 | |
| 241 | ```shell |
| 242 | cmake .. -D CMAKE_TOOLCHAIN_FILE=cmake/toolchains/armhf.cmake |
| 243 | make |
| 244 | cpack |
| 245 | ``` |
| 246 | |
| 247 | This will create a deb file and a rpm file in a new sub-directory called "pkgs" within |
| 248 | the build directory. You can use either of these packages to install the library to |
| 249 | your target machine (see the above instructions about using a package manager). |