Awesome
dtn7zero
This is a DTN7 RFC9171 compliant python implementation (work-in-progress) with a NetworkZero like API.
The current features are:
- a full bundle protocol agent (without fragment, CRC, and status-report generation support -> todo)
- a minimal TCP convergence layer
- a dtn7-rs convergence layer, using the HTTP/REST interface
- automatic local-network node-discovery via IPND module
- a standalone 'external' endpoint (which connects to a dtn7-rs via the HTTP/REST) interface
- a simplified NetworkZero like API to easily get started
- full MicroPython support (tested on an ESP32-GENERIC)
- experimental ESPNOW cla (details can be found in the source code: dtn7zero/convergence_layer_adapters/espnow_cla.py)
- (currently uses epidemic routing and in-memory storage managing)
- (with extendability for new convergence layer adapters, routing algorithms, and storage managers)
Getting Started
To use dtn7zero in your CPython environment, simply install it via pip (or pip3 on linux):
$ pip install --upgrade dtn7zero
The most simple example on what you can do:
import time
from dtn7zero import setup, start_background_update_thread
node_endpoint = setup("dtn://node1/", print)
start_background_update_thread()
node_endpoint.send(b'hello world', "dtn://node1/")
time.sleep(1)
Further examples for the 'simple' API can be found under ./examples
in the GitHub repository.
For a deeper dive into the underlying concepts and the full-fledged dtn implementation, take a look at the
dtn7zero.api
module implementation and the tests under ./test
.
MicroPython Installation Guide
Installation has been successfully tested on Windows and Linux (x86_64 and arm64). The required mpy-cross has been shown to have installation issues on Mac M1s under Mac OS X and may have to be built and installed manually.
This whole project was tested on an ESP32 (GENERIC) and this installation guide is tailored for the ESP32. If you plan to use another microcontroller you might need to do adjustments (most certainly the MicroPython installation, and the MPY_MARCH in esp-deployment.py).
Important note for linux: it may be that mpremote assumes another USB device with higher priority than the ESP32.
In that case all mpremote commands (especially inside esp-deployment.py) will fail as no communication is possible.
Check all USB devices mpremote considers in priority order with mpremote devs
.
First Time MicroPython Installation For ESP32 (GENERIC)
- download the newest firmware
- install the esp flash tool:
pip install esptool
- connect your ESP32 via USB and start a terminal at the location of the downloaded firmware
- start the following command (with the correct USB port):
esptool --chip esp32 --port /dev/ttyUSB0 erase_flash
(you may have to invoke esptool withesptool.py --chip ...
here and subsequently, you may also have hold boot to enter the bootloader on the ESP32) - start the following command (with the correct USB port and firmware name):
esptool --chip esp32 --port /dev/ttyUSB0 --baud 460800 write_flash -z 0x1000 esp32-20220618-v1.19.1.bin
(you may have hold boot again to enter the bootloader on the ESP32) - done, you may now connect to it via:
mpremote
(installation via pip:pip install mpremote
)
Update To New MicroPython Version
- download the newest firmware
- start the following command (with the correct USB port and firmware name):
esptool --chip esp32 --port /dev/ttyUSB0 --baud 460800 write_flash -z 0x1000 esp32-20220618-v1.19.1.bin
(you may have hold boot to enter the bootloader on the ESP32) - done
First Time dtn7zero Deployment
- make sure you check out the repository and the submodules (especially py-dtn7)
- install the mpremote tool:
pip install mpremote
- install the mpy-cross compiler tool:
pip install mpy-cross
(this may not work on Mac M1s under Mac OS X) - populate wlan.json with an appropriate hostname and at least one ssid -> password mapping
- check your connection to the ESP32 with:
mpremote
- copy wlan.json to your ESP32:
mpremote fs cp wlan.json :wlan.json
- copy boot.py to your ESP32:
mpremote fs cp boot.py :boot.py
- deploy the dtn7zero and dependencies onto the ESP32 (this can take a while):
python scripts/esp-deployment.py
- install required packages:
mpremote mip install urequests
andmpremote mip install datetime
- done
Continuous dtn7zero Deployment
- check your connection to the ESP32 with:
mpremote
- deploy the changes of dtn7zero and dependencies onto the ESP32 (this can take a while):
python scripts/esp-deployment.py
- done
First dtn7zero Functionality Check On MicroPython
- you may check that wlan is connecting correctly (connect via
mpremote
and press enable for a soft reset) - you may also check that you can import dtn7zero (connect via
mpremote
andimport dtn7zero
) - you can also check that everything works (run the test script
mpremote run examples/local_ping_echo.py
)
Additional MicroPython Tips & Tricks
The mpremote tool is normally interrupted by using ctrl+c
. A special case is the REPL (simply call mpremote
), which
can be exited by using ctrl+~
(tested on Windows) or ctrl+]
(Linux).
If you start a script on MicroPython (mpremote run ...
) and disconnect the console (mpremote
-> ctrl+c
) then the script
keeps running.
If you must access the REPL via mpremote, but a script is blocking, then call mpremote
and press EN (enable) on the
ESP32 for a soft-reset. Press ctrl+c
a few times to interrupt the boot.py
or main.py
script execution. The session
state is stored, so any subsequent mpremote
call will start at REPL as long as no power disconnect is performed.
You can deploy a script as main.py
on MicroPython to be run every time the microcontroller gets power.
You can also remove the script. MicroPython will only execute the script if it is present.
$ mpremote fs cp examples/remote_echo_callback.py :main.py
$ mpremote fs rm :main.py
Regarding boot.py
: it is used for user-specific setup code and this framework uses a generic boot script that adjusts
the ESP32's frequency and connects to a Wi-Fi network (blocking until success). MicroPython will create a dummy boot.py
if none is present. MicroPython will not create a dummy main.py
if none is present. MicroPython will first execute
the boot.py
and then the main.py
if it is present.
Development Information
Development Mode
You can install this project locally to directly reflect code changes in your environment. Simply run this in the project root folder (requires at least pip v21.1):
$ python -m pip install --editable .
Build
To build this project yourself you need the python build tool, as well as setuptools:
$ pip install --upgrade setuptools
$ pip install --upgrade build
Then you can simply run this command to build the project:
$ python -m build
Publish
To publish this project you will probably update the version in pyproject.toml
, build the project, and then use twine to upload the build:
$ pip install --upgrade twine
$ python -m twine upload dist/*
Useful Links
the DTN7 website: https://dtn7.github.io
dtn7 go implementation: https://github.com/dtn7/dtn7-go
dtn7 rust implementation: https://github.com/dtn7/dtn7-rs
dtn7 python bundle implementation and dtn7rs-rest-api access: https://github.com/teschmitt/py-dtn7
Bundle Protocol 7 RFC: https://datatracker.ietf.org/doc/html/rfc9171
Bundle Protocol Security (BPSec) RFC: https://datatracker.ietf.org/doc/html/rfc9172
Default Security Contexts for BPSec RFC: https://datatracker.ietf.org/doc/html/rfc9173
TCP Convergence-Layer Protocol Version 4 RFC: https://datatracker.ietf.org/doc/html/rfc9174
Minimal TCP Convergence-Layer Protocol RFC (draft): https://datatracker.ietf.org/doc/html/draft-ietf-dtn-mtcpcl-01
UDP Convergence Layer RFC (draft): https://datatracker.ietf.org/doc/html/draft-sipos-dtn-udpcl-01
Outdated Standards:
DTN URI Scheme: https://www.ietf.org/archive/id/draft-irtf-dtnrg-dtn-uri-scheme-00.html
Further Research
This is some information gathered about future mesh extensions:
-
- a special mesh standard which is based of Wi-Fi and uses the special AP_STA mode
- no micropython implementation known
-
Alternative: AP_STA mode for simultaneous AP and STA without explicit ESP-MESH usage
- only available for Arduino+C
- painlessMesh also uses this mode to build its mesh
Open End Topics / Known Issues
- fragment, CRC, status-report generation support
- dtn7rs-rest-cla and in-memory storage together use too much RAM for MicroPython (therefore the dtn7rs-rest-cla is disabled in the simple API)
- public documentation (currently all information must be gathered from doc-strings and examples)