From 4e555e26799236a62f728e36436bfc3482765360 Mon Sep 17 00:00:00 2001 From: geeksville Date: Tue, 28 Apr 2020 15:18:45 -0700 Subject: [PATCH] doc updates --- README.md | 3 +-- TODO.md | 6 +++--- bin/regen-docs.sh | 2 +- docs/meshtastic/index.html | 34 ++++++++++++++++++++++------------ 4 files changed, 27 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 8c986f4..5ecc855 100644 --- a/README.md +++ b/README.md @@ -14,8 +14,7 @@ then run the following python3 code: ``` import meshtastic - -interface = StreamInterface() # By default will try to find a meshtastic device, otherwise provide a device path like /dev/ttyUSB0 +interface = meshtastic.StreamInterface() # By default will try to find a meshtastic device, otherwise provide a device path like /dev/ttyUSB0 interface.sendData("hello world") ``` diff --git a/TODO.md b/TODO.md index 832790e..0ecd57d 100644 --- a/TODO.md +++ b/TODO.md @@ -4,16 +4,16 @@ - add fromId and toId to received messages dictionaries - update nodedb as nodes change -- make docs decent - radioConfig - getter/setter syntax: https://www.python-course.eu/python3_properties.php - DONE keep everything in dicts - document properties/fields -- include examples in readme. hello.py, textchat.py, replymessage.py all as one little demo +- include more examples: textchat.py, replymessage.py all as one little demo - have python client turn off radio sleep (use 0 for X to mean restore defaults) -- announce various places +- announce at the usual places - DONE use port enumeration to find ports https://pyserial.readthedocs.io/en/latest/shortintro.html - DONE make serial debug output optional (by providing a null stream) - DONE make pubsub work +- DONE make docs decent ## Soon after initial release diff --git a/bin/regen-docs.sh b/bin/regen-docs.sh index cd4e7b6..cf59a1e 100755 --- a/bin/regen-docs.sh +++ b/bin/regen-docs.sh @@ -1 +1 @@ -pdoc3 --html --output-dir docs meshtastic \ No newline at end of file +pdoc3 --html -f --output-dir docs meshtastic \ No newline at end of file diff --git a/docs/meshtastic/index.html b/docs/meshtastic/index.html index 6a4d9ed..58e72c7 100644 --- a/docs/meshtastic/index.html +++ b/docs/meshtastic/index.html @@ -21,7 +21,9 @@

an API for Meshtastic devices

-

Primary class: StreamInterface

+

Primary class: StreamInterface +Install with pip: "pip3 install meshtastic" +Source code on github

properties of StreamInterface:

Published PubSub topics

-

We use a publish-subscribe model to communicate asynchronous events [https://pypubsub.readthedocs.io/en/v4.0.3/ ]. +

We use a publish-subscribe model to communicate asynchronous events. Available topics:

-

Example Usage:

+

Example Usage

import meshtastic
 from pubsub import pub
 
-def onReceive(packet):
+def onReceive(packet): # called when a packet arrives
     print(f"Received: {packet}")
 
-interface = StreamInterface() # By default will try to find a meshtastic device, otherwise provide a device path like /dev/ttyUSB0
+def onConnection(): # called when we (re)connect to the radio
+    interface.sendData("hello world") # defaults to broadcast, specify a destination ID if you wish
+
+interface = meshtastic.StreamInterface() # By default will try to find a meshtastic device, otherwise provide a device path like /dev/ttyUSB0
 pub.subscribe(onReceive, "meshtastic.receive")
-interface.sendData("hello world") # defaults to broadcast, specify a destination ID if you wish
+pub.subscribe(onConnection, "meshtastic.connection.established")
@@ -65,6 +70,8 @@ interface.sendData("hello world") # defaults to broadcast, specify a d ## an API for Meshtastic devices Primary class: StreamInterface +Install with pip: "pip3 install meshtastic" +Source code on [github](https://github.com/meshtastic/Meshtastic-python) properties of StreamInterface: @@ -76,7 +83,7 @@ node in the mesh. This is a read-only datastructure. ## Published PubSub topics -We use a publish-subscribe model to communicate asynchronous events [https://pypubsub.readthedocs.io/en/v4.0.3/ ]. Available +We use a [publish-subscribe](https://pypubsub.readthedocs.io/en/v4.0.3/) model to communicate asynchronous events. Available topics: - meshtastic.connection.established - published once we've successfully connected to the radio and downloaded the node DB @@ -87,18 +94,20 @@ type of packet, you should subscribe to the full topic name. If you want to see - meshtastic.receive.data(packet) - meshtastic.node.updated(node = NodeInfo) - published when a node in the DB changes (appears, location changed, username changed, etc...) -Example Usage: - +## Example Usage ``` import meshtastic from pubsub import pub -def onReceive(packet): +def onReceive(packet): # called when a packet arrives print(f"Received: {packet}") -interface = StreamInterface() # By default will try to find a meshtastic device, otherwise provide a device path like /dev/ttyUSB0 +def onConnection(): # called when we (re)connect to the radio + interface.sendData("hello world") # defaults to broadcast, specify a destination ID if you wish + +interface = meshtastic.StreamInterface() # By default will try to find a meshtastic device, otherwise provide a device path like /dev/ttyUSB0 pub.subscribe(onReceive, "meshtastic.receive") -interface.sendData("hello world") # defaults to broadcast, specify a destination ID if you wish +pub.subscribe(onConnection, "meshtastic.connection.established") ``` """ @@ -687,6 +696,7 @@ debugOut {stream} – If a stream is provided, any debug serial output from