sascha_hemi/pycom-documentation
1
0
Fork 0
mirror of https://github.com/sascha-hemi/pycom-documentation.git synced 2026-03-21 22:06:43 +01:00
Code Issues Packages Projects Releases Wiki Activity

Pymesh corrected documentation

Browse Source
This commit is contained in:
Catalin Ioana
2019-10-31 18:15:20 +02:00
parent 47bf9a841d
commit 8644592a0f
7 changed files with 50 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
content/pymesh/_index.md
View File

@@ -20,7 +20,7 @@ _**Note: For obtaining the Pymesh firmware please follow the steps from [Pymesh
## What does Pymesh offer you?
* Ad-hoc communication network over raw-LoRa radio
* An ad-hoc communication network over raw-LoRa radio
* Multi-gateway (Border Routers) Nodes that connect Mesh-internal data with the Cloud
* Each Node uses LBS - Listen Before Talk
* Security on multiple levels

10
content/pymesh/lib-api.md
View File

@@ -8,9 +8,9 @@ aliases:
This Micropython library is included as frozen scripts in the Pymesh firmware release.
Code is open-sourced in [pycom-libraries repository](https://github.com/pycom/pycom-libraries/tree/master/lib/pymesh).
The code is open-sourced in [pycom-libraries repository](https://github.com/pycom/pycom-libraries/tree/master/lib/pymesh).
It is easily customisable and contributions are highly recommend using [Github PRs](https://github.com/pycom/pycom-libraries/pulls).
It is easily customisable and contributions are welcome using [Github PRs](https://github.com/pycom/pycom-libraries/pulls).
### Main features
@@ -40,7 +40,7 @@ A simple example of usage is in the [main.py](https://github.com/pycom/pycom-lib
## Specifications
It can be easily customised, by modifying any file from [/lib folder](https://github.com/pycom/pycom-libraries/tree/master/lib/pymesh/lib) and flashing it to the board. Automatically the uploaded file will be executed instead of the _frozen_ one, already embedded into the binary firmware.
It can be easily customised, by modifying any file from [/lib folder](https://github.com/pycom/pycom-libraries/tree/master/lib/pymesh/lib) and flashing it to the board. The uploaded file will automatically be executed instead of the _frozen_ one, which is already embedded into the binary firmware.
### Structure
@@ -55,9 +55,9 @@ It can be easily customised, by modifying any file from [/lib folder](https://gi
* setting BLE server
* auxiliary files:
* `pymesh-debug.py`
* debugging on levels, allowing dynamically changing debug level
* debugging on multiple levels, allowing dynamically changing the current debug level
* `pymesh-config.py`
* reading/writing Pymesh configuration file
* reading/writing the Pymesh configuration file
* `gps.py`
* maintaining location coordinates, as an extension `Pytrack` GPS can be used
* Mesh internals

10
content/pymesh/lib-ble-rpc.md
View File

@@ -28,11 +28,11 @@ This sets the location coordinates.
#### get_mesh_mac_list()
This returns list of distinct MAC address that are in this mesh network, for example `[mac1, mac2, mac 3]`.`
This returns the list of distinct MAC address that are within this mesh network, for example `[mac1, mac2, mac 3]`.`
#### get_mesh_pairs()
This returns list of pairs that is a mesh connection, as shown bellow:
This returns the list of pairs that form a mesh connection, as shown bellow:
```
[
@@ -69,7 +69,7 @@ This returns the node data for a specified mac address, or own data id `mac_id`
#### send_message(data)
This sends a message with another node. It return True if there is buffer to store it (to be sent).
This sends a message to another node. It return True if there is a buffer to store it (to be sent onwards).
`data` is a dictionary with the following structure:
```
@@ -84,11 +84,11 @@ This sends a message with another node. It return True if there is buffer to sto
#### send_message_was_sent(mac, msg_id)
This checks if acknowledge was received for the specified `mac` and `msg_id`. It returns `True` if message was delivered.
This checks if acknowledgement was received from the specified `mac` and `msg_id`. It returns `True` if message was delivered.
#### receive_message()
This returns the received messages, in a dictionary with the next structure:
This returns the received messages, in a dictionary with the following structure:
```
{
'b': 'text',

28
content/pymesh/lib-cli.md
View File

@@ -6,9 +6,9 @@ aliases:
## Overview
The Pymesh micropython library is included as frozen in the Pymesh firmware releases.
The Pymesh micropython library is included as a `frozen python script` in the Pymesh firmware releases.
Instead of REPL, a specific Pymesh CLI is interpreting commands and it is recognised, by starting with `>`.
Instead of REPL, a specific Pymesh CLI interprets commands. This is shown by `>`.
The CLI is executed on a separate thread inside the Pymesh library.
@@ -25,10 +25,10 @@ List of available commands
ip - display current IPv6 unicast addresses
mac - set or display the current LoRa MAC address
self - display all info about current node
mml - display the Mesh Mac List (MAC of all nodes inside this Mesh), also inquires Leader
mp - display the Mesh Pairs (Pairs of all nodes connections), also inquires Leader
mml - display the Mesh Mac List (MAC of all nodes inside this Mesh)
mp - display the Mesh Pairs (pairs of all nodes connections)
s - send message
ws - verifies if message sent was acknowledged
ws - verifies if the message sent was acknowledged
rm - verifies if any message was received
sleep - deep-sleep
br - enable/disable or display the current Border Router functionality
@@ -75,7 +75,7 @@ deepsleep_init
Cleanup code, all Alarms cb should be stopped
Going to deepsleep for 10 seconds
```
This puts the device in deepsleep for designated number of seconds.
This puts the device into deepsleep for a designated number of seconds.
```
>buf
@@ -110,20 +110,22 @@ This executes an Openthread CLI command. The list of CLI commands is [here](http
>mac
1
```
This shows LoRa MAC, this address is used as unique identifier in the Pymesh. Bellow there's a section on how to set MAC specific MAC address (useful for debugging, the MAC could be consecutive small numbers like `0x1`, `0x2`, `...`)
This shows the LoRa MAC or sets it to a known value. This address is used as a unique identifier within the Pymesh.
This can be useful for debugging and the MAC could be set to consecutive small numbers, such as `0x1`, `0x2`, ...
```
>mml
mesh_mac_list [1, 6, 2]
```
This shows the list of all MAC Nodes attached to Pymesh. It inquires Leader, which centralises this data.
This shows the list of all MAC Nodes attached to Pymesh. It inquires the Leader, which centralises this data.
```
>mp
Send pack: 0xF3 to IP fdde:ad00:beef:0:0:ff:fe00:fc00
last_mesh_pairs [[2, 6, -87], [1, 6, -77]]
```
This shows Mesh Pairs list, with each direct connected nodes (by their MAC address) and the averaged RSSI value.
This shows the Mesh Pairs list. It lists each directly connected node (by their MAC address) and the averaged RSSI value.
```
>mni
@@ -143,7 +145,7 @@ True
PACK_MESSAGE_ACK received
1945883 ================= ACK RECEIVED :) :) :)
```
This sends text messages to another Node inside Pymesh. The messaging waits for acknowledgement (ACK message type) from the destination node.
This sends text messages to another Node within the Pymesh. The messaging node waits for acknowledgement (ACK message type) from the destination node.
```
>ws
@@ -151,7 +153,7 @@ This sends text messages to another Node inside Pymesh. The messaging waits for
ACK? mac 1, id 12345 => 1
True
```
This shows if a message was acknowledged by the destination Node.
This shows if the message was acknowledged by the destination Node.
```
>rm
@@ -197,7 +199,7 @@ BR: [(net='2001:cafe:cafe:cafe::/64', preference=0)]
(state 0=Disable, 1=Enable, 2=Display [Default Display])<
Border Router state: [(net='2001:cafe:cafe:cafe::/64', preference=0)]
```
This enables/disables and shows the state of the current node as Border Router.
This enables/disables the Border Router functionality of the current node. It also shows the state of the current node as Border Router.
```
>brs
@@ -207,4 +209,4 @@ brs
(port destination [Default: 5555])<
Send BR message: {'ip': '1:2:3::4', 'b': '', 'port': 5555}
```
This sends a packet to an IP address external of the Pymesh. This packet will be received by the designated Border Router and it can be further forwarded to another network interface, like: BLE, Wifi, Sigfox or Cellular (Fipy only).
This sends a packet to an external IP address, outside of the Pymesh. The packet will be received by the designated Border Router and it can be further forwarded to another network interface, such as: BLE, Wifi, Sigfox or Cellular (Fipy only).

10
content/pymesh/licence.md
View File

@@ -10,15 +10,15 @@ In order to receive access to the Pymesh firmware releases (for Lopy4, Fipy, L01
<!-- <a href="/gitbook/assets/specsheets/Pycom_002_Specsheets_LoPy4_v2.pdf" target="\_blank"> the Pymesh LICENCE PDF document </a> -->
1. Complete the Pymesh LICENCE PDF document(not yet available), sign it and send us by [this email](mailto:catalin@pycom.io?subject=[Pymesh_LICENCE]).
1. You will receive on email an archive containing the images for all boards.
1. Extract the corresponding image, for example Lopy4.tar.gz, and upload the firmware to your board, using the [Pycom Firmware Update Tool](https://pycom.io/downloads/), like in the following image:
1. You will receive by email an archive containing the images for all boards.
1. Extract the corresponding image, for example Lopy4.tar.gz, and upload the firmware to your board, using the [Pycom Firmware Update Tool](https://pycom.io/downloads/), similar in the following image:
<img src="/gitbook/assets/pymesh/pymesh_firmware_update.png" alt="Pymesh Firmware Update" width="500"/>
## Test Pymesh firmware loading
### Method 1
The simplest method to check if Pymesh class is successfully installed, just try this code directly in REPL:
The simplest way to check if the Pymesh class has been successfully installed is to try the following code, directly in REPL:
```python
>>> from network import LoRa
@@ -36,7 +36,7 @@ Q: **I've received an error, such as `(LoadProhibited). Exception was unhandled.
A: In some cases, the NVM partition needs to be formatted. For this a format of whole Flash Memory should be performed.
This can be done using the cli version of the Firmware Update Tool, so please navigate where this app was installed (search for pycom-fwtool-cli executable) and execute:
This can be done using the cli version of the `Firmware Update Tool`, so please navigate where the app was installed (search for pycom-fwtool-cli executable) and execute:
```
pycom-fwtool-cli -p <PORT> erase_all
```
@@ -45,4 +45,4 @@ pycom-fwtool-cli -p <PORT> erase_all
* on Windows `COM10`
* on Linux `/dev/ttyACM0`
* on MacOS ``/dev/tty.usbmodemPy8eaa911`
* on MacOS `/dev/tty.usbmodemPy8eaa911`

30
content/pymesh/pymesh-br.md
View File

@@ -9,19 +9,19 @@ aliases:
## Overview
The Border Router role, of a Node inside Pymesh, takes the traffic from the Pymesh and forwards it to the Cloud (Pymesh-external).
Any node inside of the Pymesh can take on the role as a Border Router, which takes the traffic from the Pymesh and forwards it to the Cloud (Pymesh-external).
Several things must be accomplished:
* The BR node should have connection with the Cloud, using another network interface (than LoRa-Pymesh), for example: BLE, Wifi or Cellular.
* The node has to be declared as BR, so all the other nodes send packets to it, with destination Cloud.
* Dynamically multiple nodes can be BR, each of them having different priorities levels (Normal, High or Low)
* The BR with the smallest routing cost is chosen.
* If multiple BR have the same routing cost, the priority level is used.
* The Border Router node should have connection with the Cloud. This should occur using another network interface (other than LoRa-Pymesh), for example: BLE, Wifi or Cellular.
* The node has to be declared as a Border Router, so that all the other nodes send packets to it. The final destination is the Cloud.
* To add flexibility, at runtime (dynamically), multiple nodes can act as Border Routers. Each of them can have different priority levels (Normal, High or Low).
* The Border Router with the smallest routing cost is selected.
* If multiple Border Routers have the same routing cost, then the priority level is used.
## Border Router using CLI
As explained in [Pymesh CLI - Border Router section](pymesh/lib-cli/#border-router-specific), using commands `br` and `brs`, a simple testing scenario can be easily implemented.
As explained in [Pymesh CLI - Border Router section](pymesh/lib-cli/#border-router-specific), using commands `br` and `brs`, a simple test scenario can be easily implemented.
## Border Router using Pymesh API
@@ -54,14 +54,14 @@ pymesh.send_mess_external(ip, port, "Hello World")
Internally, the Border Router mechanism is implemented with the following steps:
* declare the BR network address prefix, like `2001:dead:beef:cafe::/64`
* this piece of information is sent to the `Leader` and the dataset will increase version (it will be updated)
* the dataset is propagated to all Pymesh nodes
* all the nodes will be assigned a random IPv6 unicast address with this network prefix (like `2001:dead:beef:cafe:1234:5678:9ABC:DEF0`)
* if a node sends data to an IPv6 which is external (it doesn't have prefix from Pymesh already existent networks, like `1:2:3::4`), this UDP datagram will be routed to the BR
* this UDP packet will have as source the random IPv6 from BR network address
* BR will receive the UDP datagrams for external with an appended header, which contains:
* Declare the Border Router network address prefix, for example `2001:dead:beef:cafe::/64`
* The network address prefix is then sent to the `Leader` and the dataset will increase the version, meaning that it will be updated.
* The dataset is propagated to all Pymesh nodes.
* All the nodes will be assigned a random IPv6 unicast address with this network prefix (for example `2001:dead:beef:cafe:1234:5678:9ABC:DEF0`)
* If a node sends data to an IPv6 which is external (meaning it doesn't have a prefix from already existent networks in Pymesh, for example `1:2:3::4`), then the UDP datagram will be routed to the Border Router
* This UDP packet will have as source the random IPv6 from BR network address
* The Border Router will receive the external UDP datagrams with an appended header, which contains:
* MAGIC byte: `0xBB`
* IPv6 destination as bytearray (16 bytes)
* port destination as 2 bytes (1-65535 values).
* the IPv6 destination is important so BR could actually route (forward) the UDP datagram content to the right interface (Wifi/BLE/cellular).
* The IPv6 destination is important, because it means that the Border Router can route (forward) the UDP datagram content to the correct interface (Wifi/BLE/cellular).

8
content/pymesh/simple-example.md
View File

@@ -6,11 +6,11 @@ aliases:
## What is Pymesh micropython library?
Pymesh micropython library is a set of scripts included (as frozen) in the Pymesh firmware binary release (not yet released).
The Pymesh Micropython library is a set of frozen scripts in the Pymesh firmware binary release (which has not yet been released).
[Open-source on github](https://github.com/pycom/pycom-libraries/tree/master/lib/pymesh)
It allows users to use Pymesh in a few lines of code, as shown in the following code snippet.
It allows users to access Pymesh in a few lines of code, as shown in the following code snippet.
```python
@@ -97,9 +97,9 @@ while True:
## Output
An example of output is bellow.
An example of possible output is below.
At any point pressing `Enter` will try to execute CLI commands, more details are presented in [Pymesh library CLI](/pymesh/lib-cli).
At any point pressing `Enter` will result in the attempt to execute CLI commands. More details are found in [Pymesh library CLI](/pymesh/lib-cli).
```