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