deuxyeux/RTNode-HeltecV4
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: RNodeTHV4 boundary mode firmware for Heltec V4

Browse Source 
Bridges LoRa mesh and TCP/WiFi backbone networks using microReticulum.
Based on microReticulum_Firmware with boundary mode additions:
- BoundaryMode.h: State management and EEPROM persistence
- BoundaryConfig.h: WiFi captive portal for configuration
- TcpInterface.h: TCP backbone interface with HDLC framing
- Display.h: Custom OLED layout with network status indicators
- Transport/Identity library patches for embedded memory constraints
This commit is contained in:
James L
2026-02-22 18:25:20 -05:00
commit a746937390
134 changed files with 28567 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

123
Console/source/guides/install_firmware.md Executable file
View File

@@ -0,0 +1,123 @@
[date]: <> (2023-01-12)
[title]: <> (Installing RNode Firmware on Supported Devices)
[image]: <> (images/g2p.webp)
[excerpt]: <> (If you have a T-Beam or LoRa32 device handy, it is very easy to get it set up for all the things that the RNode firmware allows you to do.)
<div class="article_date">{DATE}</div>
# Installing RNode Firmware on Supported Devices
Do you have one of the devices available that the RNode Firmware supports? In that case, it is very easy to turn it into a working RNode by using the `rnodeconf` autoinstaller.
With the firmware installed, you can use your newly created RNode as:
- A [LoRa interface for Reticulum]({ASSET_PATH}m/interfaces.html#rnode-lora-interface)
- A LoRa packet sniffer with [LoRaMon](https://unsigned.io/loramon/)
- A Linux network interface using the [tncattach program]({ASSET_PATH}pkg/tncattach.zip)
- A LoRa-based TNC for almost any amateur radio packet application
So let's get started! You will need either a **LilyGO T-Beam v1.1**, a **LilyGO LoRa32 v2.0**, a **LilyGO LoRa32 v2.1** or a **Heltec LoRa32 v2** device. More supported devices are added regularly, so it might be useful to check the latest [list of supported devices]({ASSET_PATH}supported.html) as well.
It is currently recommended to use one of the following devices: A **LilyGO LoRa32 v2.1** (also known as **TTGO T3 v1.6.1**) or a **LilyGO T-Beam v1.1**.
![Compatible LoRa devices]({ASSET_PATH}images/g2p.webp)
<center>*Some of the device types compatible with this installation guide*</center>
## Device Variations
Some devices come with transceiver chips that are currently unsupported by the RNode Firmware. Currently devices with an **SX1276** or **SX1278** chip are supported. Support for **SX1262**, **SX1268** and **SX1280** is being added. Please support the development with [donations]({ASSET_PATH}donate.html), if you would like to see these chips supported.
> **Beware!** Some devices, like the T-Beam, use SiLabs USB chips. These may need [additional drivers](https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers) to work well on macOS and Windows. Linux usually has up-to-date drivers pre-installed. The SiLabs driver may also experience conflicts with earlier, pre-installed versions of the driver, causing a *resource busy* error, which can be fixed by [removing the old driver](https://community.platformio.org/t/mac-usb-port-detected-but-won-t-upload/20663/2).
## Preparations
To get started, you will need to install at least version 2.1.0 of the [RNode Configuration Utility]({ASSET_PATH}m/using.html#the-rnodeconf-utility).
The `rnodeconf` program is included in the `rns` package. Please read [these instructions]({ASSET_PATH}s_rns.html) for more information on how to install it from this repository, or from the Internet. If installation goes well, you can now move on to the next step.
## Install The Firmware
We are now ready to start installing the firmware. To install the RNode Firmware on your devices, run the RNode autoinstaller using this command:
```txt
rnodeconf --autoinstall
```
The installer will now ask you to insert the device you want to set up, scan for connected serial ports, and ask you a number of questions regarding the device. When it has the information it needs, it will install the correct firmware and configure the necessary parameters in the device EEPROM for it to function properly.
If the install goes well, you will be greated with a success message telling you that your device is now ready.
> **Please Note!** If you are connected to the Internet while installing, the autoinstaller will automatically download any needed firmware files to a local cache before installing.
> If you do not have an active Internet connection while installing, you can extract and use the firmware from this device instead. This will **only** work if you are building the same type of RNode as the device you are extracting from, as the firmware has to match the targeted board and hardware configuration.
If you need to extract the firmware from an existing RNode, run the following command:
```
rnodeconf --extract
```
If `rnodeconf` finds a working RNode, it will extract and save the firmware from the device for later use. You can then run the auto-installer with the `--use-extracted` option to use the locally extracted file:
```
rnodeconf --autoinstall --use-extracted
```
This also works for updating the firmware on existing RNodes, so you can extract a newer firmware from one RNode, and deploy it onto other RNodes using the same method. Just use the `--update` option instead of `--autoinstall`.
## Verify Installation
To confirm everything is OK, you can query the device info with:
```txt
rnodeconf --info /dev/ttyUSB0
```
Remember to replace `/dev/ttyUSB0` with the actual port the installer used in the previous step. You should now see `rnodeconf` connect to your device and show something like this:
```txt
[20:11:22] Opening serial port /dev/ttyUSB0...
[20:11:25] Device connected
[20:11:25] Current firmware version: 1.26
[20:11:25] Reading EEPROM...
[20:11:25] EEPROM checksum correct
[20:11:25] Device signature validated
[20:11:25]
[20:11:25] Device info:
[20:11:25] Product : LilyGO LoRa32 v2.0 850 - 950 MHz (b0:b8:36)
[20:11:25] Device signature : Validated - Local signature
[20:11:25] Firmware version : 1.26
[20:11:25] Hardware revision : 1
[20:11:25] Serial number : 00:00:00:02
[20:11:25] Frequency range : 850.0 MHz - 950.0 MHz
[20:11:25] Max TX power : 17 dBm
[20:11:25] Manufactured : 2022-01-27 20:10:32
[20:11:25] Device mode : Normal (host-controlled)
```
On the hardware side, you should see the status LED flashing briefly approximately every 2 seconds. If all of the above checks out, congratulations! Your RNode is now ready to use. If your device has a display, it should also come alive and show you various information related to the device state.
If you want to use it with [Reticulum]({ASSET_PATH}s_rns.html), [Nomad Network]({ASSET_PATH}s_nn.html), [LoRaMon](https://unsigned.io/loramon), or other such applications, leave it in the default `Normal (host-controlled)` mode.
If you want to use it with legacy amateur radio applications that work with KISS TNCs, you should [set it up in TNC mode]({ASSET_PATH}guides/tnc_mode.html).
## External RGB LED
If you are using a **LilyGO LoRa32 v2.1** device, you can connect an external **NeoPixel RGB LED** for device status using the following setup:
- Connect the NeoPixel **V+** pin to the **3.3v** pin on the board.
- Connect the NeoPixel **GND** pin to the **GND** pin on the board.
- Connect the NeoPixel **DATA** pin to **IO Pin 12** on the board.
For the firmware to activate the NeoPixel LED, you must also make specific choices in the autoinstaller guide:
- When asked what type of device you have, select **A specific kind of RNode**.
- When asked what model the device is, select the **Handheld v2.x RNode** that matches the frequency of your board.
## External Display & LEDs
If you are using a **LilyGO T-Beam** device, you can connect an external **SSD1306 OLED** display using the following setup:
- The **SSD1306**-based display must be set to use **I2C** and address `0x3D`
- Connect display **GND** to T-Beam **GND**
- Connect display **Vin** to suitable power-supplying pin on the T-Beam
- Connect display **RST** to T-Beam **Pin 13**
- Connect display **I2C CLK** to T-Beam **SCL** / **Pin 22**
- Connect display **I2C DATA** to T-Beam **SDA** / **Pin 21**
On **T-Beam** devices, you can also connect external RX/TX LEDs to **Pin 2** and **Pin 4**.

237
Console/source/guides/loracomms.md Executable file
View File

@@ -0,0 +1,237 @@
[date]: <> (2023-01-14)
[title]: <> (Private, Secure and Uncensorable Messaging Over a LoRa Mesh)
[image]: <> (images/g1p.webp)
[excerpt]: <> (Or: How to set up a completely private, independent and encrypted communication system in half an hour, using stuff you can buy for under $100.)
<div class="article_date">{DATE}</div>
# Private, Secure and Uncensorable Messaging Over a LoRa Mesh
*Or: How to set up a completely private, independent and encrypted communication system in half an hour, using stuff you can buy for under $100.*
![]({ASSET_PATH}images/g1p.webp)
In this post, we will explore how two people, Alice and Bob, can set up a LoRa mesh communication system for their use that has the following characteristics:
- Allows both real-time and asynchronous text message communication between Alice and Bob.
- Works *completely* indpendently of any infrastructure outside the control of Alice and Bob. Even if the Internet, cellular networks and the power grid fails, Alice and Bob must still be able to communicate.
- Is completely private and outside the reach of automated surveillance, and does not reveal any identifying information about Alice or Bob, nor any contents of or information about their conversations.
In later parts of this series, we will expand the system to provide these oppertunities to an entire community, and add other mediums like Packet Radio, but for now we will focus on learning the basics by just establishing a Free Communications System between Alice and Bob.
To accomplish this, we will be building a small and simple system based on freely available and Open Source software. To realise our system we will need the following components:
- A networking system that can function reliably and efficiently even without any functional Internet infrastructure available. This will be provided by [Reticulum]({ASSET_PATH}r/index.html).
- Software that Alice and Bob can interact with on their computers and mobile devices to actually communicate with each other. This will be provided by the programs [Nomad Network]({ASSET_PATH}s_nn.html) and [Sideband]({ASSET_PATH}s_sideband.html).
- Radio hardware that Reticulum can use to cover the 7 kilometer distance between Bobs apartment and Alices house. This will be provided by installing the [RNode Firmware]({ASSET_PATH}guides/install_firmware.html) on a couple of small LoRa radio modules that can be purchased cheaply off Amazon or similar online vendors.
As you might have already guessed, the "magic glue" that acutally makes this entire system possible is [Reticulum]({ASSET_PATH}r/index.html).
Reticulum is a complete networking stack that was designed to handle challenging situations and requirements like this. Reticulum is an incredibly flexible networking platform, that can use almost anything as a carrier for digital information transfer, and it can automatically form secure mesh networks with very minimal resources, infrastructure and setup.
Please do keep in mind though, that at the time of writing this, Reticulum is still in beta. There might be bugs and security issues that have not yet been discovered. You can keep up with such things, and get updates on the general development and releases, over on the [Reticulum GitHub page](https://github.com/markqvist/reticulum).
The user-facing software that Alice and Bob will be installing already includes Reticulum, so there is no complicated installation and configuration setups, and getting everything up and running will be quite simple. The requirements are also very minimal, and everything can run on hardware they already have available, be that an old computer, a Raspberry Pi, or an Android phone.
Let's get started.
# LoRa Radio Setup
The first step is to get the LoRa radios prepared and installed. I have written in more length and details about these subjects in other posts on this site ([Installing RNode Firmware on Supported Devices]({ASSET_PATH}guides/install_firmware.html) and [How To Make Your Own RNodes]({ASSET_PATH}guides/make_rnodes.html), so this article will just quickly guide you through the basics required to get up and running. For much more information, read the above articles.
First of all, Alice and Bob need to get a compatible piece of radio hardware to use. Had they been living closer to each other, they might have just been able to use WiFi, but they need to cover a distance of more than 7 kilometers, so they decide to go with a couple of LoRa radios.
They take a look at the RNode Firmware [Supported Devices List]({ASSET_PATH}supported.html), and decide to go with a couple of LilyGO T-Beam devices. They could have also used others, and they don't need to choose the same device, as long as they are within the same frequency range, all compatible devices work with Reticulum and can communicate with each other, as soon as the RNode Firmware has been installed on them.
![]({ASSET_PATH}images/lora_rnodes.webp)
Once the devices arrive, it is time to get the firmware installed. For this they will need a computer running some sort of Linux. Alice has a computer with Ubuntu installed, so they decide to use that. Since Python3 came installed as standard with the OS, Alice can go ahead and install the RNode configuration program by simply opening a terminal and typing:
```
pip install rnodeconf
```
The above command installs the program they need to flash the LoRa radios with the right firmware. If for some reason Python3 had not already been installed on Alices computer, she would have had to install it first with the command `sudo apt install python python-pip`.
Now that the firmware installer is ready, it is time to actually get the firmware on to the devices. Alice launches the installer with the following command:
```
rnodeconf --autoinstall
```
After this she is greated with an interactive guide that asks a few questions about the device type, grabs the latest firmware files, and installs them onto the device. After repeating with the second device, that is all there is to it, and the LoRa radios are now ready for use with Reticulum.
# Installation at Alices House
To get a better signal, Alice mounts her LoRa radio in the attic of her house. She then runs a USB cable from the mounting location to the computer she wants to use for messaging, and plugs the cable into the computer. The LoRa radio is now directly connected to her computer via USB, and receives power from it when the computer is on.
At her computer (running Ubuntu Linux), she installs the Nomad Network program by entering the following command in a terminal:
```
pip install nomadnet
```
After a few seconds, Nomad Network and Reticulum is installed and ready to use. She can now run the Nomad Network client by entering the following command:
```
nomadnet
```
All required directories and configuration files will now be created, and the client will start up. After a few seconds, Alice will be greeted with a screen like this:
![]({ASSET_PATH}images/nn_init.webp)
Confirming that everything is installed and working, it is time to add the LoRa radio as an interface that Reticulum can use. To do this, she opens up the Reticulum configuration file (located at `˜/.reticulum/config`) in a text editor.
By referring to the [RNode LoRa Interface]({ASSET_PATH}m/interfaces.html#rnode-lora-interface) section of the [Reticulum Manual]({ASSET_PATH}m), she can just copy-and-paste in a new configuration section for the interface, and edit the radio parameters to her requirements. She ends up with a configuration file that looks like this in it's entirity:
```
[reticulum]
enable_transport = False
share_instance = Yes
shared_instance_port = 37428
instance_control_port = 37429
panic_on_interface_error = No
[logging]
loglevel = 4
[interfaces]
[[Default Interface]]
type = AutoInterface
interface_enabled = True
[[RNode LoRa Interface]]
type = RNodeInterface
interface_enabled = True
port = /dev/ttyUSB0
frequency = 867200000
bandwidth = 125000
txpower = 7
spreadingfactor = 8
codingrate = 5
```
*Please note that the assignment and use of radio frequency spectrum is completely outside the scope of this exploratory post. Laws and regulations about spectrum use vary greatly around the world, and you will have to do your own research for what frequencies and modes you can use in your location, and what licenses, if any, are required for any given use case.*
Alice can now start the Nomad Network client again, and this time around it will initialise and use the LoRa radio installed in her attic. Having completed Alices part of the setup, lets move on to Bobs apartment.
# Installation at Bobs Apartment
Bob likes his messaging to happen on a handy device like a phone, so he decides to go with the [Sideband]({ASSET_PATH}s_sideband.html) app instead of Nomad Network. He goes to the [download page](https://github.com/markqvist/Sideband/releases/latest) and installs the APK on his Android phone. He now needs a way to connect to the LoRa radio already running at Alices house to establish communication.
Since he doesn't want to walk around with the LoRa radio constantly dangling by a USB cable from his phone, he decides to set up a Reticulum gateway in his apartment using a Raspberry Pi he had lying around. The RNode LoRa radio will connect via USB to the Raspberry Pi, and the Raspberry Pi will be connected to the WiFi network in his apartment.
This way, any device on his WiFi network (including his Android phone) will be able to route information through the LoRa radio as well. Reticulum takes care of everything automatically, and there is no need to configure addresses, subnet, routing rules or anything.
Both his WiFi router and the Rasperry Pi is powered by a small battery system, so even if the power goes out, the system will be able to stay on for several days on the battery, and indefinitely if he props up a solar panel on his balcony.
Bob installs a fresh copy of Raspberry Pi OS on the small computer, and in the terminal issues the following command to install Reticulum:
```
pip install rns
```
In this case, Bob will not be running any user-facing software on the Raspberry Pi itself, so instead he starts Reticulum as a service, by running the `rnsd` program, to check that everything installed correctly:
```
rnsd
```
After a moment, the following output is shown from the `rnsd` program, signalling that everything is working properly, but that a new, default configuration file has just been created:
```
[2022-03-26 17:14:05] [Notice] Could not load config file, creating default configuration file...
[2022-03-26 17:14:05] [Notice] Default config file created. Make any necessary changes in /home/bob/.reticulum/config and restart Reticulum if needed.
[2022-03-26 17:14:09] [Notice] Started rnsd version 0.3.3
```
Bob terminates the `rnsd` program, and then connects the LoRa radio to the Raspberry Pi with a USB cable. Since he doesn't have any particular access to the roof or attic of the building, he just sticky-tapes the LoRa radio to a window facing in the general direction of Alices house.
He then proceeds to add the same interface configuration to his Reticulum configuration file as Alice did, so that the radio parameters of their respective LoRa radios match each other.
To allow other devices on his network to route through his new Reticulum gateway, he also adds the line `enable_transport = yes` to his Reticulum config file, so the file in it's entirity looks like this:
```
[reticulum]
enable_transport = Yes
share_instance = Yes
shared_instance_port = 37428
instance_control_port = 37429
panic_on_interface_error = No
[logging]
loglevel = 4
[interfaces]
[[Default Interface]]
type = AutoInterface
interface_enabled = True
[[RNode LoRa Interface]]
type = RNodeInterface
interface_enabled = True
port = /dev/ttyUSB0
frequency = 867200000
bandwidth = 125000
txpower = 7
spreadingfactor = 8
codingrate = 5
```
After starting the program again, this time using `rnsd -vvv` to get more verbose output, he can now see that the LoRa radio is correctly configured and used by Reticulum:
```
[2022-03-26 18:17:43] [Debug] Bringing up system interfaces...
[2022-03-26 18:17:43] [Verbose] AutoInterface[Default Interface] discovering peers for 1.8 seconds...
[2022-03-26 18:17:45] [Notice] Opening serial port /dev/ttyUSB0...
[2022-03-26 18:17:47] [Notice] Serial port /dev/ttyUSB0 is now open
[2022-03-26 18:17:47] [Verbose] Configuring RNode interface...
[2022-03-26 18:17:47] [Verbose] Wating for radio configuration validation for RNodeInterface[RNode LoRa Interface]...
[2022-03-26 18:17:47] [Debug] RNodeInterface[RNode LoRa Interface] Radio reporting frequency is 867.2 MHz
[2022-03-26 18:17:47] [Debug] RNodeInterface[RNode LoRa Interface] Radio reporting bandwidth is 125 KHz
[2022-03-26 18:17:47] [Debug] RNodeInterface[RNode LoRa Interface] Radio reporting TX power is 7 dBm
[2022-03-26 18:17:47] [Debug] RNodeInterface[RNode LoRa Interface] Radio reporting spreading factor is 8
[2022-03-26 18:17:47] [Debug] RNodeInterface[RNode LoRa Interface] Radio reporting coding rate is 5
[2022-03-26 18:17:47] [Verbose] RNodeInterface[RNode LoRa Interface] On-air bitrate is now 3.1 kbps
[2022-03-26 18:17:47] [Notice] RNodeInterface[RNode LoRa Interface] is configured and powered up
[2022-03-26 18:17:48] [Debug] System interfaces are ready
[2022-03-26 18:17:48] [Verbose] Configuration loaded from /home/bob/.reticulum/config
[2022-03-26 18:17:50] [Verbose] Loaded 0 path table entries from storage
[2022-03-26 18:17:50] [Verbose] Loaded 0 tunnel table entries from storage
[2022-03-26 18:17:50] [Verbose] Transport instance <a5dc367015b30f2d7b59> started
[2022-03-26 18:17:50] [Notice] Started rnsd version 0.3.3
```
Everything is ready, and when Bob launches the Sideband appplication on his phone, Alice and him will now be able to communicate securely and independently of any other infrastructure.
# Communication
Both the [Nomad Network]({ASSET_PATH}s_nn.html) program and the [Sideband]({ASSET_PATH}s_sidband.html) application use a cryptographic message delivery system named [LXMF]({ASSET_PATH}s_lxmf.html), that in turn uses Reticulum for encryption and privacy guarantees. Both Nomad Network and Sideband are *LXMF clients*.
Much like many different e-mail clients exist, so can many different LXMF clients, and they can all communicate with each other, which is why Alice and Bob can message each other even though they prefer to use very different kinds of user-facing software.
An LXMF addresses consist of 32 hexadecimal characters, and are usually encapsulated in single angle quotation marks like this: `<9824f6367015b30f2d7b8a24bc6205d7>`.
Nobody controls the allocation of addresses, and since the address space is so huge, and governed by cryptographic principles, you can create as many or as few adresses as you need.
Since you can just create them with freely avaible software, and without any sort of permission from anyone, they are never linked to any personally identifiable information either. They are completely and truly anonymous from the beginning, and you control how much or how little of your identity you associate with them.
For an LXMF address to be reachable for direct-delivery instant messaging on a Reticulum network, it must announce it's public keys on the network. Both Sideband and Nomad Network allows you to send an announce on the network, and both programs can be configured to do so automatically when they start. If you only want to use the system for "email-style" communication (via LXMF propagation nodes), you don't *need* to send any announces on the network, but to learn how it all works, it is a good idea to just set the programs to automatically announce at start up.
To make sure his public cryptographic key is known by the network, Bob taps the **Announce** button in the Sideband app:
<center><p><img src="{ASSET_PATH}images/an1.webp"/></p></center>
After a few seconds, Bobs announce shows up in the **Announce Stream** section of the Nomad Network program on Alices computer:
<center><p><img src="{ASSET_PATH}images/nn_an.webp"/></p></center>
Using the received announce, Alice starts a conversation with Bob. Either one of them could also have started the conversation by manually typing in the others LXMF address in their program, but in many cases it can be convenient to use the announces. Now that everything is ready, they exchange a few messages to test the system. On Bobs Android phone, this looks like this:
<center><p><img style="max-width: 100%; width: 300px;" src="{ASSET_PATH}images/3_conv.webp"/></p></center>
And on Alices computer running Nomad Network, it looks like this:
<center><p><img src="{ASSET_PATH}images/nn_conv.webp"/></p></center>
Although pretty useful, what we have explored here does not even begin to scratch the surface of what is possible with Reticulum and associated software. I hope you will find yourself inspired to explore and read deeper into the documentation and available software.
To learn more, take a look at the [Learn]({ASSET_PATH}learn.html) section.

111
Console/source/guides/make_rnodes.md Executable file
View File

@@ -0,0 +1,111 @@
[date]: <> (2023-01-10)
[title]: <> (How To Make Your Own RNodes)
[image]: <> (images/g3p.webp)
[excerpt]: <> (This article will outline the general process, and provide the information you need, for building your own RNode from a few basic modules. The RNode will be functionally identical to a commercially purchased board.)
# How To Make Your Own RNodes
This article will outline the general process, and provide the information you need, for building your own RNode from a few basic modules. The RNode will be functionally identical to a purchased device.
Once you have learned the put together a custom RNode with your own choice of components, you can use these skills to create your own RNode designs from scratch, using either a custom-designed PCB, or simply by mounting your choice of modules in a enclosure or case.
If you haven't already, you migh also want to check out how to [install the RNode firmware directly on pre-made LoRa development boards]({ASSET_PATH}guides/install_firmware.html).
![A Homemade RNode]({ASSET_PATH}images/g3p.webp)
<center>*A homemade RNode, based on an ESP32 board and a transceiver module, ready for use*</center>
Since there is not *one right way* to cut this pie, this article will probably not give the *exact* steps for the combination of components you choose, but will instead attempt to provide you with the information you need to build RNodes from a wide variety of microcontroller boards and LoRa modules. Generally speaking, you will need three things to construct a working RNode:
- A supported microcontroller board
- A supported transceiver module
- A way to mount and connect the two
## Preparing the Hardware
Currently, the RNode firmware supports a variety of different microcontrollers, and more are being added regurlarly. That means that there is a *lot* of boards to choose from. You can probably use most boards that are based on either the **ATmega1284P**, **ATmega2560** or **ESP32** microcontrollers. Regarding microcontroller boards there is a few key points to take note of:
- You will need to connect the transceiver module over the SPI bus. This means that the board should have SPI pins for exposed for you to connect to. UART-only modules will **not** work.
- Logic voltage levels must match the transceiver module you are using, or you will have to add a voltage level converter in between the two devices, that is fast enough for the clock of the SPI bus (usually 8 or 10MHz). I recommend using a microcontroller and transceiver module with matching logic levels. Most will be 3.3 volts.
- Apart from the SPI pins for *clock*, *chip select*, *MOSI* and *MISO*, you will also need an output pin for a *reset* line to the transceiver module, and one **interrupt-capable** input pin for the interrupt signal from the transceiver module. Almost all boards should have plenty of IO available for this, but you might as well make sure before ordering anything.
- You need to choose a board that can provide enough power on it's internal regulators to power the transceiver module while it is transmitting. This can draw quite a bit of power, and some boards only have very small 3.3v regulators, which will not cut it while driving the transmitter at full tilt.
Regarding the LoRa transceiver module, there is going to be an almost overwhelming amount of options to choose from. To narrow it down, here are the essential characteristics to look for:
- The RNode firmware needs a module based on the **Semtech SX1276**, **Semtech SX1278**, **SX1262**, **SX1268** and **SX1280** LoRa transceiver ICs. These come in several different variants, for all frequency bands from about 150 MHz to 2500 MHz.
- The module *must* expose the direct SPI bus to the transceiver chip. UART based modules that add their own communications layer will not work.
- The module must also expose the *reset* line of the chip, and provide the **DIO0** (or other relevant) interrupt signal *from* the chip.
- As mentioned above, the module must be logic-level compatible with the microcontroller you are using, unless you want to add a level-shifter. Resistor divider arrays will most likely not work here, due to the bus speeds required.
Keeping those things in mind, you should be able to select a suitable combination of microcontroller board and transceiver module.
## Assembling the RNode
Ok, having gone through the endless combinations and selected a board and a module, you are actually almost done. Connecting the devices together is pretty simple, and should only take a few minutes. I recommend that you place both devices in a solderless breadboard initially, to make sure everything is working as expected. Once you have a working setup, you can make it more durable and permanent by soldering it to a prototyping board, and connecting permanent lines between the devices.
In the photo above I used an Adafruit Feather ESP32 board and a ModTronix inAir4 module. That will result in an RNode suitable for the 420 MHz to 520 MHz range. To complete the device I did the following:
1. Connect the GND pin of the microcontroller board to the GND rail of the breadboard.
2. Connect the GND pin of the transceiver module to the GND rail of the breadboard.
3. Connect the 3.3 volt output line of the microcontroller board to the V_IN pin of the transceiver module.
4. Connect the *chip select* pin of the microcontroller board to the *chip select* pin of the transceiver module.
5. Connect the *SPI clock* pin of the microcontroller board to the *SPI clock* pin of the transceiver module.
6. Connect the *MOSI* pin of microcontroller board to the *MOSI* pin of the transceiver module.
7. Connect the *MISO* pin of the microcontroller board to the *MISO* pin of the transceiver module.
8. Connect the *transceiver reset* pin of the microcontroller board to the *reset* pin of the transceiver module.
9. Connect the *DIO0* pin of the transceiver module to the *DIO0 interrupt pin* of the microcontroller board.
10. You can optionally connect transmit and receiver LEDs to the corresponding pins of the microcontroller board.
The pin layouts of your transceiver module and microcontroller board will vary, but you can look up the correct pin assignments for your processor type and board layout in the [Config.h](https://github.com/markqvist/RNode_Firmware/blob/master/Config.h) file of the [RNode Firmware](https://unsigned.io/rnode_firmware).
### Loading the Firmware
Once the hardware is assembled, you are ready to load the firmware onto the board and configure the configuration parameters in the boards EEPROM. Luckily, this process is completely automated by the [RNode Configuration Utility](https://markqvist.github.io/Reticulum/manual/using.html#the-rnodeconf-utility). To prepare for loading the firmware, make sure that `python` and `pip` is installed on your system, then install the `rns` package (which includes the `rnodeconf` program) by issuing the command:
```txt
pip install rns
```
If installation goes well, you can now move on to the next step.
> *Take Care*: A LoRa transceiver module **must** be connected to the board for the firmware to start and accept commands. If the firmware does not verify that the correct transceiver is available on the SPI bus, execution is stopped, and the board will not accept commands. If you find the board unresponsive after installing the firmware, or EEPROM configuration fails, double-check your transceiver module wiring!
Having double-checked that everything is connected correctly, it is time to power up the board and install the firmware. Run the `rnodeconf` autoinstaller by executing the command:
```txt
rnodeconf --autoinstall
```
The installer will now ask you to insert the device you want to set up, scan for connected serial ports, and ask you a number of questions regarding the device. When it has the information it needs, it will install the correct firmware and configure the necessary parameters in the device EEPROM for it to function properly.
If the install goes well, you will be greated with a success message telling you that your device is now ready. To confirm everything is OK, you can query the device info with:
```txt
rnodeconf --info /dev/ttyUSB0
```
Remember to replace `/dev/ttyUSB0` with the actual port the installer used in the previous step. You should now see `rnodeconf` connect to your device and show something like this:
```txt
[2022-01-27 20:11:22] Opening serial port /dev/ttyUSB0...
[2022-01-27 20:11:25] Device connected
[2022-01-27 20:11:25] Current firmware version: 1.26
[2022-01-27 20:11:25] Reading EEPROM...
[2022-01-27 20:11:25] EEPROM checksum correct
[2022-01-27 20:11:25] Device signature validated
[2022-01-27 20:11:25]
[2022-01-27 20:11:25] Device info:
[2022-01-27 20:11:25] Product : LilyGO LoRa32 v2.0 850 - 950 MHz (b0:b8:36)
[2022-01-27 20:11:25] Device signature : Validated - Local signature
[2022-01-27 20:11:25] Firmware version : 1.26
[2022-01-27 20:11:25] Hardware revision : 1
[2022-01-27 20:11:25] Serial number : 00:00:00:02
[2022-01-27 20:11:25] Frequency range : 850.0 MHz - 950.0 MHz
[2022-01-27 20:11:25] Max TX power : 17 dBm
[2022-01-27 20:11:25] Manufactured : 2022-01-27 20:10:32
[2022-01-27 20:11:25] Device mode : Normal (host-controlled)
```
On the hardware side, you should see the status LED flashing briefly approximately every 2 seconds. If all of the above checks out, congratulations! Your RNode is now ready to use.
If you want to use it with [Reticulum]({ASSET_PATH}s_rns.html), [Nomad Network]({ASSET_PATH}s_nn.html), [LoRaMon](https://unsigned.io/loramon), or other such applications, leave it in the default `Normal (host-controlled)` mode.
If you want to use it with legacy amateur radio applications that work with KISS TNCs, you should [set it up in TNC mode]({ASSET_PATH}guides/tnc_mode.html).

22
Console/source/guides/tnc_mode.md Executable file
View File

@@ -0,0 +1,22 @@
[date]: <> (2023-01-07)
[title]: <> (Using an RNode With Amateur Radio Software)
[image]: <> (images/g4p.webp)
[excerpt]: <> (If you want to use an RNode with amateur radio applications, like APRS or a packet radio BBS, you will need to put the device into TNC Mode. In this mode, an RNode will behave exactly like a KISS-compatible TNC, which will make it usable with any amateur radio software.)
<div class="article_date">{DATE}</div>
# Using an RNode With Amateur Radio Software
If you want to use an RNode with amateur radio applications, like APRS or a packet radio BBS, you will need to put the device into *TNC Mode*. In this mode, an RNode will behave exactly like a KISS-compatible TNC, which will make it usable with any amateur radio software that can talk to a KISS TNC over a serial port.
You can use the [RNode Configuration Utility]({ASSET_PATH}m/using.html#the-rnodeconf-utility) to change settings on your device, including putting it into TNC mode.
The `rnodeconf` program is included in the `rns` package. Please read [these instructions]({ASSET_PATH}s_rns.html) for more information on how to install it from this repository, or from the Internet.
With the `rnodeconf` program installed, you can put your RNode into TNC mode simply by entering the command:
```
rnodeconf -T /dev/ttyUSB0
```
Remember to replace `/dev/ttyUSB0` with the actual port your RNode is connected to. The program will now ask you for the channel configuration parameters, like frequency, bandwidth, transmission power and so on. It is also possible to specify all the parameters at once on the command line, see the `rnodeconf --help` for information on how to do this.
That's all there is to it! Your RNode is now configured in TNC mode, and ready for use with amateur radio applications.