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:

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.
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:

LILYGO TTGO T3 v2 1.6 LoRa module.
LILYGO TTGO T3-S3 v1.2 LoRa module (2.4 Ghz version not tested/supported).
LILYGO TTGO T Beam LoRa module.
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 :

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

talk32 /dev/tty.usbserial001 repl

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

Freakwan

Install / Use

README