FreakWAN

FreakWAN is an effort to create a LoRa-based open WAN network, completely independent from Internet and the cellular phones networks. The network built with FreakWAN has two main goals:

1. To provide both a plaintext and an encrypted distributed chat system, that can be used by technology amateurs, or in places where internet is not available and during disasters.
2. As a side effect of the first goal, to create a robust protocol over LoRa to support other applications, like sensors data collection, home automation applications, not having the usual range limitations of OOK/FSK communcation, and so forth.

Our goal is to cover parts of the Sicily with such a network. The code will be freely available to anyone wanting to build their own LoRa WANs on top of this software. The main features of our implementation and protocol are the following:

• A distributed network based on LoRa and broadcast routing.
• Basic chat features, ability to send medias (like small images).
• Different group chat or data channels (including one-to-one chats) using encryption to separate them.
• Configurable number of retransmissions with random delays.
• First-hop acknowledges of messages sent.
• Symmetric encryption with AES in CBC mode, with support for integrity detection and multiple concurrent keys: each group of clients knowing a given key is part of a virtual group. The network is collaborative for encrypted messages: even nodes that are not able to decrypt a given message can broadcast it, since the encrypted part is not vital to perform relaying of messages.
• Sensing of nearby nodes, via HELLO messages (advertising).
• Bandwidth usage mitigation features.
• Duty cycle tracking.
• Local storage of messages in the device flash, with automatic deletion of old messages.
• Simple home-made driver for the SX1276 and SX1262 LoRa chip. In general, no external dependencies. Runs with vanilla MicroPython installs.
• OLED terminal alike output. OLED burning pixels protection.
• CLI interface via USB serial and Bluetooth LE.
• IRC interface: the device can work as a bot over the IRC protocol.
• Simple to understand, hackable code base.

This code is currently a functional work in progress, designed to work with the following ESP32-based devices:

1. LILYGO TTGO T3 v2 1.6 LoRa module.
2. LILYGO TTGO T3-S3 v1.2 LoRa module (2.4 Ghz version not tested/supported).
3. LILYGO TTGO T Beam LoRa module.
4. LILYGO T-WATCH S3.

However changing the pins in the configuration, to adapt it to other ESP32 modules that have an SX1276, SX1262 LoRa chips, and an SSD1306 or ST7789 display (or no dislay, in headless mode), should be very little work. T-ECHO devices are also supported, even if with less features, in the C port of FreanWAN, under the techo-port directory, but the T-ECHO port is still alpha quality software.

FreakWAN is implemented in MicroPython, making use only of default libraries.

Installation

• Install MicroPython on your device. Follow this instructions to get the right MicroPython version:
• MicroPython versions > 1.19.1 and < 1.22.2 have buggy bluetooth stack, so make sure to use 1.22.2 (or greater) or if you want to stick with something old, use 1.19.1.
• Don't bother installing a MicroPython specific for the LILYGO devices. Just grab the standard ESP32 image (but not for the T3-S3, read more).
• The T3-S3 (and probably the T-BEAM S3, which we don't support at the moment, because we don't have the device) have a 4MB flash which is not compatible with the default MicroPython image for 8MB flash. You can find a working image directly inside this repository under the device directory.
• To flash your device, follow the MicroPython instructions in the download page of your device. For the T3-S3, don't forget to press the boot button while powering it up, otherwise you will not be able to flash it. Then, with esptool.py, perform the erase_flash command followed by the write_flash with the parameters specified in the MicroPython download page.
• Clone this repository, and edit wan_config.py to set your nickname and status message, set the frequency according to your device. Warning: make sure to set the right frequency based on the LoRa module you own, and make sure your antenna is already installed before using the software, or you may damage your hardware, (but I would like to report that we started the device with the wrong freuqnecy several times and nothing happened: still, proceed at your own risk).

• Copy one of the files inside the devices folder in the main folder as device_config.py, for instance if I have a T3 v2 1.6 device, I will do:

  cp devices/device_config.t3_v2_1.6.py ./device_config.py

• Transfer all the .py files in the root directory of this project in your device. To transfer the files, you can use mpremote (pip3 install mpremote should be enough), or an alternative (and slower, but sometimes more compatible) tool that we wrote, called talk32. Talk32 is not as fast as mpremote at transferring files, but sometimes mpremote does not work with certain devices and talk32 does (and the other way around).

(NOTE: you need the : below, is not an error)

mpremote cp *.py :

or

talk32 /dev/tty.usbserial001 put *.py

Please note that you don't need both the command lines. Just one depending on the tool you use.

• Restart your device: you can either power it off/on, or use mpremote repl and hit Ctrl_D to trigger a soft reset. Sometimes devices also have a reset button. If everything is fine you will see the splash screen and then the program version.
• If you are using a T-WATCH S3, or other recent Lyligo devices based on ESP32-S3, and your splash screen freezes (the waves should move and then the splash screen should disappear, if everything works well), please try to disable BLE from wan_config.py.

Usage

The two simplest ways to send commands to the device, write messages that will be broadcasted and also receive messages sent by other users, it is to use the USB or Bluetooth serial.

Serial CLI

To obtain a serial command line interface, make sure the device is connected via an USB cable with your computer. Than connect to the device serial with talk32, minicom, screen or whatever serial terminal you want to use. Normally the bound rate is 115200. Example of command lines and tools you could use:

mpremote repl

or

talk32 /dev/tty.usbserial001 repl

or

screen /dev/tty.usbserial001 115200

Of course the name of the device is just an example. Try ls /dev/tty* to see the list of possible device names in your computer.

Once you connect, you will see the device logs, but you will also be able to send bang commands or messages to the chat (see below).

Bluetooth low energy CLI

It is possible to use the device via Bluetooth LE, using one of the following applications: * Android: install one of the many BLE UART apps available. We recommend the Serial Bluetooth Terminal app. It works great out of the box, but for the best experience open the settings, go to the Send tab, and select clear input on send. An alternative is nRF Toolbox, select the UART utility service, connect to the device and send a text message or just !help. * iPhone: BLE Terminal HM-10 works well and is free. There are other more costly options. * Linux Desktop: install Freakble following the project README. * For MacOS, there is a BLE UART app directly inside this software distribution under the osx-bte-cli directory. Please read the README file that is there.

Sending commands and messages

Using one of the above, you can talk with the device, and chat with other users around, sending CLI commands. If you just type some text, it will be sent as message in the network. Messages received from the network are also shown in the serial console. If you send a valid command starting with the ! character, it will be executed as a command, in order to show information, change the device configuration and so forth. For now you can use: * !automsg [on/off] to disable enable automatic messages used for testing. * !bat to show the battery level. * !preset <name> to set a LoRa preset. Each preset is a specific spreading, bandwidth and coding rate setup. To see all the available presets write !preset help. * !sp, !bw, !cr to change the spreading, bandwidth and coding rate independently, if you wish. * !pw changes the TX power. Valid values are from 2 to 20 (dbms). Default is 17dbms. * !ls shows nodes around. This is the list of nodes that your node is able to sense, via HELLO messages. * !ping [<text>] sends a ping to test connectivity with nearby nodes. Only nodes within direct radio range will respond (unless in quiet mode). If no text is provided, defaults to "ping". Responses show the responder's nickname, original text, round-trip time (RTT), and bidirectional signal strength (outbound RSSI when they received your ping, inbound RSSI when you received their pong). This is a fire-and-forget operation, pings are never relayed. Works even in quiet mode (you can send pings, but won't reply to pings from others). * !font big|small will change between an 8x8 and a 5x7 (4x6 usable area) font. * !image <image-file-name> send an FCI image (see later about images). * !last [<count>] show the last messages received, taking them from the local storage of the device. * !config [save|reset] to save (or reset) certain configuration parameters (LoRa radio parameters, automsg, irc, wifi, ...) that will be reloaded at startup. * !irc <stop|start> starts or stops the IRC interface. * !telegram <start|stop|token> starts, stops and sets the token of the Telegram bot. * !wifi help, to see all the WiFi configuration subcommands. Using this command you can add and remove WiFi networks, connect or disconnect the WiFi (required for the IRC and Telegram interface), and so forth. * !quiet <yes|no>, to enable quiet mode (default is off). In this mode, the device sends only the smallest amount of data needed, that is the data messages that we want to send. No ACKs are sent in reply to data messages, nor HELLO messages to advertise our presence in the network. Packets are not relayed in this mode, nor data is transmitted multiple times. Basically this mode is designed to save channel bandwidth, at the expense of advanced FreakWAN features, when there are many active devices and we want to make sure the LoRa channel is not continuously busy. * !b0, this is the same as pressing the button 0 on the devices (if they have one). Will switch the device screen to the next view.

New bang commands are added constantly, so try !help to see what is available. We'll try to take this README in sync, especially after the first months of intense development will be finished.

Using the device via Telegram

When FreakWAN is located in some fixed location with WiFi access, it is possible to put it online as a Telegram bot. This way it is possible to receive the messages the device receives via LoRa as Telegram messages, and at the same time it is possible to send commands and messages writing to the bot.

To use this feature, follow the instructions below:

1. Create your bot using the Telegram @BotFather.

2. After obtaining your bot token (it's basically the bot API key) use the following commands in the FreakWAN cli (either via USB or BLE) or alternatively edit wan_config.py to set the same parameters.

   !wifi add networkname password !wifi start networkname !telegram token !telegram start

Now use your Telegram application in order to sent !help to the bot, and wait for the reply. If you can receive the reply correclty, Freakwan will also set the target of your messages, that is, the account you used to talk with the bot the first time. Now you are ready to save your configuration with:

!config save

Using the device via IRC

FreakWAN is able to join IRC, as a bot. It can receive messages and commands via IRC, and also show messages received via LoRa into an IRC channel. Edit wan_config.py and enable IRC by setting the enabled flag to True, and configuring a WiFi network. Upload the modified file inside the device and restart it. Another way to enable IRC is to use bang commands via Bluetooth, like that:

!wifi add networkname password
!wifi start networkname
!irc start
!config save (only if you want to persist this configuration)

The device, by default, will enter the ##Freakwan-<nickname> channel of irc.libera.chat (please, note the two # in the channel name), and will listen for commands there. The same commands you can send via Bluetooth are also available via IRC. Because of limitations with the ESP32 memory and the additional MicroPython memory usage, SSL is not available, so FreakWAN will connect to IRC via the TCP port 6667, which is not encrypted.

Encrypted messages

By default LoRa messages are sent in clear text and will reach every device that is part of the network, assuming it is configured with the same LoRa frequency, spreading, bandwidth and coding rate. However, it is possible to send encrypted messages that will reach only other users with a matching symmetric key. For instance, if Alice and Bob want to communicate in a private way, they will set the same key, let's say abcd123, in their devices. Bob will do:

!addkey alice abcd123

While Alice will do:

!addkey bob abcd123

(Note: they need to use much longer and hard to guess key! A good way to generate a key is