hardware.rst
1 .. _hardware-main: 2 3 *********************** 4 Communications Hardware 5 *********************** 6 7 One of the truly valuable aspects of Reticulum is the ability to use it over 8 almost any conceivable kind of communications medium. The :ref:`interface types<interfaces-main>` 9 available for configuration in Reticulum are flexible enough to cover the use 10 of most wired and wireless communications hardware available, from decades-old 11 packet radio modems to modern millimeter-wave backhaul systems. 12 13 If you already have or operate some kind of communications hardware, there is a 14 very good chance that it will work with Reticulum out of the box. In case it does 15 not, it is possible to provide the necessary glue with very little effort using 16 for example the :ref:`PipeInterface<interfaces-pipe>` or the :ref:`TCPClientInterface<interfaces-tcpc>` 17 in combination with code like `TCP KISS Server <https://github.com/simplyequipped/tcpkissserver>`_ 18 by `simplyequipped <https://github.com/simplyequipped>`_. 19 20 It is also very easy to write and load :ref:`custom interface modules<interfaces-custom>` 21 into Reticulum, allowing you to communicate with more or less anything you can think of. 22 23 While this broad support and flexibility is very useful, an abundance of options 24 can sometimes make it difficult to know where to begin, especially when you are 25 starting from scratch. 26 27 This chapter will outline a few different sensible starting paths to get 28 real-world functional wireless communications up and running with minimal cost 29 and effort. Two fundamental devices categories will be covered, *RNodes* and 30 *WiFi-based radios*. Additionally, other common options will be briefly described. 31 32 Knowing how to employ just a few different types of hardware will make it possible 33 to build a wide range of useful networks with little effort. 34 35 Combining Hardware Types 36 ======================== 37 38 It is useful to combine different link and hardware types when designing and 39 building a network. One useful design pattern is to employ high-capacity point-to-point 40 links based on WiFi or millimeter-wave radios (with high-gain directional antennas) 41 for the network backbone, and using LoRa-based RNodes for covering large areas with 42 connectivity for client devices. 43 44 45 .. _rnode-main: 46 47 RNode 48 ===== 49 50 Reliable and general-purpose long-range digital radio transceiver systems are 51 commonly either very expensive, difficult to set up and operate, hard to source, 52 power-hungry, or all of the above at the same time. In an attempt to alleviate 53 this situation, the transceiver system *RNode* was designed. It is important to 54 note that RNode is not one specific device, from one particular vendor, but 55 *an open plaform* that anyone can use to build interoperable digital transceivers 56 suited to their needs and particular situations. 57 58 An RNode is a general purpose, interoperable, low-power and long-range, reliable, 59 open and flexible radio communications device. Depending on its components, it can 60 operate on many different frequency bands, and use many different modulation 61 schemes, but most commonly, and for the purposes of this chapter, we will limit 62 the discussion to RNodes using *LoRa* modulation in common ISM bands. 63 64 **Avoid Confusion!** RNodes can use LoRa as a *physical-layer modulation*, but it 65 does not use, and has nothing to do with the *LoRaWAN* protocol and standard, commonly 66 used for centrally controlled IoT devices. RNodes use *raw LoRa modulation*, without 67 any additional protocol overhead. All high-level protocol functionality is handled 68 directly by Reticulum. 69 70 .. _rnode-creating: 71 72 Creating RNodes 73 ^^^^^^^^^^^^^^^ 74 RNode has been designed as a system that is easy to replicate across time and 75 space. You can put together a functioning transceiver using commonly available 76 components, and a few open source software tools. While you can design and build RNodes 77 completely from scratch, to your exact desired specifications, this chapter 78 will explain the easiest possible approach to creating RNodes: Using common 79 LoRa development boards. This approach can be boiled down to two simple steps: 80 81 1. Obtain one or more :ref:`supported development boards<rnode-supported>` 82 2. Install the RNode firmware with the :ref:`automated installer<rnode-installation>` 83 84 Once the firmware has been installed and provisioned by the install script, it 85 is ready to use with any software that supports RNodes, including Reticulum. 86 The device can be used with Reticulum by adding an :ref:`RNodeInterface<interfaces-rnode>` 87 to the configuration. 88 89 .. _rnode-supported: 90 91 Supported Boards and Devices 92 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 93 To create one or more RNodes, you will need to obtain supported development 94 boards or completed devices. The following boards and devices are supported 95 by the auto-installer. 96 97 ------------ 98 99 .. image:: graphics/board_tbeam_supreme.png 100 :width: 75% 101 :align: center 102 103 LilyGO T-Beam Supreme 104 """"""""""""" 105 - **Transceiver IC** Semtech SX1262 or SX1268 106 - **Device Platform** ESP32 107 - **Manufacturer** `LilyGO <https://lilygo.cn>`_ 108 109 ------------ 110 111 .. image:: graphics/board_tbeam.png 112 :width: 75% 113 :align: center 114 115 LilyGO T-Beam 116 """"""""""""" 117 - **Transceiver IC** Semtech SX1262, SX1268, SX1276 or SX1278 118 - **Device Platform** ESP32 119 - **Manufacturer** `LilyGO <https://lilygo.cn>`_ 120 121 ------------ 122 123 .. image:: graphics/board_t3s3.png 124 :width: 50% 125 :align: center 126 127 LilyGO T3S3 128 """"""""""" 129 - **Transceiver IC** Semtech SX1262, SX1268, SX1276 or SX1278 130 - **Device Platform** ESP32 131 - **Manufacturer** `LilyGO <https://lilygo.cn>`_ 132 133 ------------ 134 135 .. image:: graphics/board_rak4631.png 136 :width: 45% 137 :align: center 138 139 RAK4631-based Boards 140 """""""""""""""""""" 141 - **Transceiver IC** Semtech SX1262 or SX1268 142 - **Device Platform** nRF52 143 - **Manufacturer** `RAK Wireless <https://www.rakwireless.com>`_ 144 145 ------------ 146 147 .. image:: graphics/board_opencomxl.png 148 :width: 45% 149 :align: center 150 151 OpenCom XL 152 """""""""""""""""""" 153 - **Transceiver ICs** Semtech SX1262 and SX1280 (dual transceiver) 154 - **Device Platform** nRF52 155 - **Manufacturer** `Liberated Embedded Systems <https://liberatedsystems.co.uk/>`_ 156 157 ------------ 158 159 .. image:: graphics/board_rnodev2.png 160 :width: 68% 161 :align: center 162 163 Unsigned RNode v2.x 164 """"""""""""""""""" 165 - **Transceiver IC** Semtech SX1276 or SX1278 166 - **Device Platform** ESP32 167 - **Manufacturer** `unsigned.io <https://unsigned.io>`_ 168 169 ------------ 170 171 .. image:: graphics/board_t3v21.png 172 :width: 46% 173 :align: center 174 175 LilyGO LoRa32 v2.1 176 """""""""""""""""" 177 - **Transceiver IC** Semtech SX1276 or SX1278 178 - **Device Platform** ESP32 179 - **Manufacturer** `LilyGO <https://lilygo.cn>`_ 180 181 ------------ 182 183 .. image:: graphics/board_t3v20.png 184 :width: 46% 185 :align: center 186 187 LilyGO LoRa32 v2.0 188 """""""""""""""""" 189 - **Transceiver IC** Semtech SX1276 or SX1278 190 - **Device Platform** ESP32 191 - **Manufacturer** `LilyGO <https://lilygo.cn>`_ 192 193 ------------ 194 195 .. image:: graphics/board_t3v10.png 196 :width: 46% 197 :align: center 198 199 LilyGO LoRa32 v1.0 200 """""""""""""""""" 201 - **Transceiver IC** Semtech SX1276 or SX1278 202 - **Device Platform** ESP32 203 - **Manufacturer** `LilyGO <https://lilygo.cn>`_ 204 205 ------------ 206 207 .. image:: graphics/board_tdeck.png 208 :width: 45% 209 :align: center 210 211 LilyGO T-Deck 212 """"""""""""" 213 - **Transceiver IC** Semtech SX1262 or SX1268 214 - **Device Platform** ESP32 215 - **Manufacturer** `LilyGO <https://lilygo.cn>`_ 216 217 ------------ 218 219 .. image:: graphics/board_techo.png 220 :width: 45% 221 :align: center 222 223 LilyGO T-Echo 224 """"""""""""" 225 - **Transceiver IC** Semtech SX1262 or SX1268 226 - **Device Platform** nRF52 227 - **Manufacturer** `LilyGO <https://lilygo.cn>`_ 228 229 ------------ 230 231 .. image:: graphics/board_t114.png 232 :width: 58% 233 :align: center 234 235 Heltec T114 236 """"""""""" 237 - **Transceiver IC** Semtech SX1262 or SX1268 238 - **Device Platform** nRF52 239 - **Manufacturer** `Heltec Automation <https://heltec.org>`_ 240 241 ------------ 242 243 .. image:: graphics/board_heltec32v4.png 244 :width: 58% 245 :align: center 246 247 Heltec LoRa32 v4.0 248 """""""""""""""""" 249 - **Transceiver IC** Semtech SX1262 250 - **Device Platform** ESP32 251 - **Manufacturer** `Heltec Automation <https://heltec.org>`_ 252 253 ------------ 254 255 .. image:: graphics/board_heltec32v30.png 256 :width: 58% 257 :align: center 258 259 Heltec LoRa32 v3.0 260 """""""""""""""""" 261 - **Transceiver IC** Semtech SX1262 or SX1268 262 - **Device Platform** ESP32 263 - **Manufacturer** `Heltec Automation <https://heltec.org>`_ 264 265 ------------ 266 267 .. image:: graphics/board_heltec32v20.png 268 :width: 58% 269 :align: center 270 271 Heltec LoRa32 v2.0 272 """""""""""""""""" 273 - **Transceiver IC** Semtech SX1276 or SX1278 274 - **Device Platform** ESP32 275 - **Manufacturer** `Heltec Automation <https://heltec.org>`_ 276 277 ------------ 278 279 .. _rnode-installation: 280 281 Installation 282 ^^^^^^^^^^^^ 283 284 Once you have obtained compatible boards, you can install the `RNode Firmware <https://github.com/markqvist/RNode_Firmware>`_ 285 using the `RNode Configuration Utility <https://github.com/markqvist/rnodeconfigutil>`_. 286 If you have installed Reticulum on your system, the ``rnodeconf`` program will already be 287 available. If not, make sure that ``Python3`` and ``pip`` is installed on your system, and 288 then install Reticulum with with ``pip``: 289 290 .. code:: 291 292 pip install rns 293 294 Once installation has completed, it is time to start installing the firmware on your 295 devices. Run ``rnodeconf`` in auto-install mode like so: 296 297 .. code:: 298 299 rnodeconf --autoinstall 300 301 The utility will guide you through the installation process by asking a series of 302 questions about your hardware. Simply follow the guide, and the utility will 303 auto-install and configure your devices. 304 305 .. _rnode-usage: 306 307 Usage with Reticulum 308 ^^^^^^^^^^^^^^^^^^^^ 309 When the devices have been installed and provisioned, you can use them with Reticulum 310 by adding the :ref:`relevant interface section<interfaces-rnode>` to the configuration 311 file of Reticulum. In the configuraion you can specify all interface parameters, 312 such as serial port and on-air parameters. 313 314 315 WiFi-based Hardware 316 =================== 317 318 It is possible to use all kinds of both short- and long-range WiFi-based hardware 319 with Reticulum. Any kind of hardware that fully supports bridged Ethernet over the 320 WiFi interface will work with the :ref:`AutoInterface<interfaces-auto>` in Reticulum. 321 Most devices will behave like this by default, or allow it via configuration options. 322 323 This means that you can simply configure the physical links of the WiFi based devices, 324 and start communicating over them using Reticulum. It is not necessary to enable any IP 325 infrastructure such as DHCP servers, DNS or similar, as long as at least Ethernet is 326 available, and packets are passed transparently over the physical WiFi-based devices. 327 328 .. only:: html 329 330 .. image:: graphics/radio_rblhg5.png 331 :width: 49% 332 333 .. image:: graphics/radio_is5ac.png 334 :width: 49% 335 336 Below is a list of example WiFi (and similar) radios that work well for high capacity 337 Reticulum links over long distances: 338 339 - `Ubiquiti airMAX radios <https://store.ui.com/collections/operator-airmax-devices>`_ 340 - `Ubiquiti LTU radios <https://store.ui.com/collections/operator-ltu>`_ 341 - `MikroTik radios <https://mikrotik.com/products/group/wireless-systems>`_ 342 343 This list is by no means exhaustive, and only serves as a few examples of radio hardware 344 that is relatively cheap while providing long range and high capacity for Reticulum 345 networks. As in all other cases, it is also possible for Reticulum to co-exist with IP 346 networks running concurrently on such devices. 347 348 Ethernet-based Hardware 349 ======================= 350 351 Reticulum can run over any kind of hardware that can provide a switched Ethernet-based 352 medium. This means that anything from a plain Ethernet switch, to fiber-optic systems, 353 to data radios with Ethernet interfaces can be used by Reticulum. 354 355 The Ethernet medium does not need to have any IP infrastructure such as DHCP servers 356 or routing set up, but in case such infrastructure does exist, Reticulum will simply 357 co-exist with. 358 359 To use Reticulum over Ethernet-based mediums, it is generally enough to use the included 360 :ref:`AutoInterface<interfaces-auto>`. This interface also works over any kind of 361 virtual networking adapter, such as ``tun`` and ``tap`` devices in Linux. 362 363 Serial Lines & Devices 364 ====================== 365 366 Using Reticulum over any kind of raw serial line is also possible with the 367 :ref:`SerialInterface<interfaces-serial>`. This interface type is also useful for 368 using Reticulum over communications hardware that provides a serial port interface. 369 370 Packet Radio Modems 371 =================== 372 373 Any packet radio modem that provides a standard KISS interface over USB, serial or TCP 374 can be used with Reticulum. This includes virtual software modems such as 375 `FreeDV TNC <https://github.com/xssfox/freedv-tnc>`_ and `Dire Wolf <https://github.com/wb2osz/direwolf>`_.