History

Agie Ashwood 161944eab7 Docs: Mandocs		2024-08-06 14:32:40 +00:00
..
Components	Manual source linking. Ouch.	2024-08-06 14:29:10 +00:00
Cryptography	Docs: Title fixing rst	2024-08-06 14:30:08 +00:00
Daisy	Docs: Title fixing rst	2024-08-06 14:30:08 +00:00
Packets	Docs: Title fixing rst	2024-08-06 14:30:08 +00:00
Siph	Docs: Title fixing rst	2024-08-06 14:30:08 +00:00
Splash	Manual source linking. Ouch.	2024-08-06 14:29:10 +00:00
Sponge	Docs: Title fixing rst	2024-08-06 14:30:08 +00:00
Transceiver	Docs: Title fixing rst	2024-08-06 14:30:08 +00:00
readme.md	Docs: Mandocs	2024-08-06 14:32:40 +00:00
run.md	Manual source linking. Ouch.	2024-08-06 14:29:10 +00:00
ui.md	Manual source linking. Ouch.	2024-08-06 14:29:10 +00:00

readme.md

PierMesh documentation

System Overview

PierMesh has two main events loops to learn about: the TUI and the service.

TUI

🔗 Docs

🔗 Source

The TUI is provided via Textual's library. It's a relatively simple application that gives us a quick overview of system statistics in the way of memory and cpu usage as well as scrollable logs. You can toggle full screen logs with f and close the TUI and service with q.

The Service

PierMesh runs a number of loops under the hood. These are primarily initialized in the main loop of run with a special logging loop outside of that.

Note that we make heavy use of Meshtastic's Python API.

run

🔗 run.py docs

🔗 run.py source

run.main

In run.main we (in order)

Initialize the Node class to a global nodeOb.
Wait for x seconds determined by command line arguments (see the falin and marcille scripts in scripts)
Initialize our Transceiver class (and the corresponding hardware)
Initialize our Server class
Create an async task running the Node.spongeListen method which looks for updates from the filter system
Kick the loop on with await asyncio.sleep(1) (we do this to kick on all async loops so I will omit this step going forward)
Create an async task running the Transceiver.checkProgress method which checks for packet reception progress and resends packets if necessary
Create an async task running Node.monitor which checks and reports system usage
Create an async task running the Transceiver.announce method which broadcasts a Packets.Message containing network mapping information
Last we start the Microdot server loop

..

Travelling out of the run.main thread to the primary main code we see the other two threads: one running the logPassLoop loop which is created in the same way as the main thread: lplThread = threading.Thread(target=asyncio.run, args=(logPassLoop(),)) and one running the TUI loop which has it's own system we just kick on by instantiating the TUI class and calling .run() on.

Packet lifecycle

Prior to this we've been talking relatively high level but if you've read this far you probably want more low level details. Let's talk about packets.

Packets.Packet

This is a base singular packet. At the very least a packet will contain: a packets ID which determines what set of packets (message) a singular packet belongs to if any, a packetNumber which determines which order the data will be put in, a packetCount which is, well a count of all the packets in a set of packets and in most cases data which is an lzma compressed msgpack encoded chunk of data to be fused together when the full set of packets is received.

Packets.HeaderPacket

This is the metadata packet for a set of packets (message) which handles the details necessary for routing and action triggering

Packets.Message

A set of packets instantiated primarily from lzma compressed msgpack encoded bytes

You keep saying msgpack what is that?

msgpack is what I landed on for bundling metadata and arbitrary bytes after initially using bson as msgpack is leaner, simpler and better adopted for cross platform data interchange

Transmitting

Once we have our msgpack encoded lzma compressed data we can send it with Transceiver.addPackets this method creates a Message and sends each Packet (dumped to binary data) over LoRa using Meshtastic's Python interface via the Transceiver.send method.

Receiving

On the other end when we receive a Packet we pass it directly into Sponge.base.sieve which checks: if it's msgpack encoded and if it's a packet sent by the same node. In both cases it skips the packet, otherwise we sieve!

Sieving

Primarily in this stage we are gathering packets and adding them to an object containing all of the packet info and data we've received for that Message.

Once a Message is completed we pass it on to the appropriate protocol from Sponge.Protocols. These will pass the Message wherever it needs to go from there which can be any number of places.

To avoid unnecessary manual documentation labor for future devs I will not list everything that could happen here but here are some examples:

Updating a Catch
Sending a message up to a peer on the node
Sending a Diffie Hellman handshake

Fin

Well not really, there's more to learn but these are the basics. There's more in the docs above and you can always submit an issue or reach me at info@piermesh.net or on Tumblr at utopicwork.