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>`_.