mirror of
https://github.com/meshtastic/meshtastic.git
synced 2024-09-21 00:27:35 -07:00
118 lines
3.4 KiB
Plaintext
118 lines
3.4 KiB
Plaintext
---
|
|
id: python
|
|
title: Meshtastic Python Development
|
|
sidebar_position: 5
|
|
sidebar_label: Python
|
|
---
|
|
|
|
## A note to developers of this lib
|
|
|
|
We use the Visual Studio Code (VScode) default python formatting conventions (autopep8). So if you use that IDE you should be able to use "Format Document" and not generate unrelated diffs. If you use some other editor, please do not change formatting on lines you have not changed yourself.
|
|
|
|
### Building
|
|
|
|
```shell title="To build a new release"
|
|
apt install pandoc
|
|
sudo pip3 install markdown pdoc3 webencodings pyparsing twine autopep8 pylint pytest pytest-cov
|
|
```
|
|
|
|
```shell title="For development"
|
|
pip3 install -r requirements.txt
|
|
```
|
|
|
|
### Linting
|
|
|
|
```shell
|
|
pylint meshtastic
|
|
```
|
|
|
|
### Testing
|
|
|
|
#### Install and run pytest
|
|
|
|
- For more verbosity, add `-v` or even `-vv`
|
|
|
|
```shell
|
|
pip3 install .
|
|
pytest -vv
|
|
```
|
|
|
|
```shell title="Run just unit tests"
|
|
pytest
|
|
# or (more verbosely)
|
|
pytest -m unit
|
|
# or
|
|
make
|
|
```
|
|
|
|
```shell title="Run just integration tests"
|
|
pytest -m int
|
|
```
|
|
|
|
```shell title="Run the smoke test with only one device connected serially (aka smoke1)"
|
|
pytest -m smoke1
|
|
```
|
|
|
|
:::caution
|
|
Running `smoke1` will reset values on the device, including the region to 1 (US).
|
|
Be sure to hit the reset button on the device after the test is completed.
|
|
:::
|
|
|
|
```shell title="Run the smoke test with only two device connected serially (aka smoke2)"
|
|
pytest -m smoke2
|
|
```
|
|
|
|
```shell title="Run the wifi smoke test"
|
|
pytest -m smokewifi
|
|
```
|
|
|
|
```shell title="Run a specific test"
|
|
pytest -msmoke1 meshtastic/tests/test_smoke1.py::test_smoke1_info
|
|
|
|
# or to run a specific smoke2 test
|
|
pytest -m smoke2 meshtastic/tests/test_smoke2.py::test_smoke2_info
|
|
|
|
# or to run a specific smoke_wifi test
|
|
pytest -m smokewifi meshtastic/tests/test_smoke_wifi.py::test_smokewifi_info
|
|
```
|
|
|
|
**Add another classification of tests such as `unit` or `smoke1`**
|
|
|
|
See [pytest.ini](https://github.com/meshtastic/Meshtastic-python/blob/master/pytest.ini).
|
|
|
|
```shell title="To see the unit test code coverage"
|
|
pytest --cov=meshtastic
|
|
# or if want html coverage report
|
|
pytest --cov-report html --cov=meshtastic
|
|
# or
|
|
make cov
|
|
```
|
|
|
|
```shell title="To see slowest unit tests, you can run"
|
|
pytest --durations=0
|
|
# or
|
|
make slow
|
|
```
|
|
|
|
### Generate the Python API documentation
|
|
|
|
Pre-generated: [API documentation](https://python.meshtastic.org)
|
|
|
|
```shell
|
|
bin/regen-docs.sh
|
|
```
|
|
|
|
## Wire encoding
|
|
|
|
When sending protobuf packets over serial or TCP each packet is preceded by uint32 sent in network byte order (big endian).
|
|
The upper 16 bits must be 0x94C3. The lower 16 bits are packet length (this encoding gives room to eventually allow quite large packets).
|
|
|
|
Implementations validate length against the maximum possible size of a BLE packet (our lowest common denominator) of 512 bytes. If the
|
|
length provided is larger than that we assume the packet is corrupted and begin again looking for 0x4403 framing.
|
|
|
|
The packets flowing towards the device are ToRadio protobufs, the packets flowing from the device are FromRadio protobufs.
|
|
The 0x94C3 marker can be used as framing to (eventually) resync if packets are corrupted over the wire.
|
|
|
|
Note: the 0x94C3 framing was chosen to prevent confusion with the 7 bit ascii character set. It also doesn't collide with any valid utf8 encoding. This makes it a bit easier to start a device outputting regular debug output on its serial port and then only after it has received a valid packet from the PC, turn off unencoded debug printing and switch to this
|
|
packet encoding.
|