Merge pull request #186 from mkinney/docs

migrate docs to main project docs

Author: mkinney

.gitignore

@@ -1,4 +1,5 @@
 README
+docs/
 build
 dist
 *.egg-info

Makefile

@@ -6,6 +6,10 @@ test:
 install:
 	pip install .
 
+# generate the docs (for local use)
+docs:
+	pdoc3 --html -f --output-dir docs meshtastic
+
 # lint the codebase
 lint:
 	pylint meshtastic

README.md

@@ -7,262 +7,7 @@ A python client for using [Meshtastic](https://www.meshtastic.org) devices. This
 
 Full documentation including examples [here](https://meshtastic.github.io/Meshtastic-python/meshtastic/index.html).
 
-Installation is easily done through the Python package installer pip (note, you must use pip version 20 or later):
+The library api is documented [here](https://meshtastic-python.vercel.app/meshtastic/index.html)
 
-- check that your computer has the required serial drivers installed, if not download them from [here](https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers).
-- check that your computer has Python 3 installed.
-- check that your computer has "pip3" installed, if not follow [this guide](https://www.makeuseof.com/tag/install-pip-for-python/).
-- check that pytap2 is installed by pip3. If not, install it:
-
-```
-sudo pip3 install --upgrade pytap2
-```
-
-- install meshtastic:
-
-```
-sudo pip3 install --upgrade meshtastic
-```
-
-An example using Python 3 code to send a message to the mesh:
-
-```
-import meshtastic
-interface = meshtastic.serial_interface.SerialInterface() # By default will try to find a meshtastic device, otherwise provide a device path like /dev/ttyUSB0
-interface.sendText("hello mesh") # or sendData to send binary data, see documentations for other options.
-interface.close()
-```
-
-For the rough notes/implementation plan see [TODO](https://github.com/meshtastic/Meshtastic-python/blob/master/TODO.md).
-
-## Command line tool
-
-This pip package will also install a "meshtastic" command line executable, which displays packets sent over the network as JSON and lets you see serial debugging information from the meshtastic devices. The source code for this tool is also a good [example](https://github.com/meshtastic/Meshtastic-python/blob/master/meshtastic/__main__.py) of a 'complete' application that uses the meshtastic python API.
-
-NOTE: This command is not run inside of python; you run it from your operating system shell prompt directly. If when you type "meshtastic" it doesn't find the command and you are using Windows: Check that the python "scripts" directory [is in your path](https://datatofish.com/add-python-to-windows-path/).
-
-To display a (partial) list of the available commands:
-
-```
-meshtastic -h
-```
-
-### Changing device settings
-
-You can also use this tool to set any of the device parameters which are stored in persistent storage. For instance, here's how to set the device
-to keep the bluetooth link alive for eight hours (any usage of the bluetooth protcol from your phone will reset this timer)
-
-```
-meshtastic --set wait_bluetooth_secs 28800
-Connected to radio...
-Setting preference wait_bluetooth_secs to 28800
-Writing modified preferences to device...
-```
-
-Or to set a node at a fixed position and never power up the GPS.
-
-```
-meshtastic --setlat 25.2 --setlon -16.8 --setalt 120
-```
-
-Or to configure an ESP32 based board to join a wifi network as a station (wifi support in the device code is coming soon):
-
-```
-meshtastic --set wifi_ap_mode false --set wifi_ssid mywifissid --set wifi_password mywifipsw
-```
-
-Or to configure an ESP32 to run as a Wifi access point:
-
-```
-meshtastic --set wifi_ap_mode true --set wifi_ssid mywifissid --set wifi_password mywifipsw
-```
-
-Once an a node is connected to a Wi-Fi network, you can use the `--host` option to access it instead of using the USB serial bridge:
-
-```
-meshtastic --host Meshtastic-0123.lan --info --nodes
-```
-
-For a full list of preferences which can be set (and their documentation) see [here](https://meshtastic.org/docs/developers/protobufs/api#radioconfiguserpreferences).
-
-### Changing channel settings
-
-The channel settings can be changed similiarly. Either by using a standard (sharable) meshtastic URL or you can set partiular channel parameters (for advanced users).
-
-The URL is constructed automatically based off of the current channel settings. So if you want to customize a channel you could do something like:
-
-```
-meshtastic --ch-set name mychan --ch-set channel_num 4 --info
-```
-
-This will change some channel params and then show device info (which will include the current channel URL)
-
-You can even set the channel preshared key to a particular AES128 or AES256 sequence.
-
-```
-meshtastic --ch-set psk 0x1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b --info
-```
-
-Use "--ch-set psk none" to turn off encryption.
-
-Use "--ch-set psk random" will assign a new (high quality) random AES256 key to the primary channel (similar to what the Android app does when making new channels).
-
-Use "--ch-set psk default" to restore the standard 'default' (minimally secure, because it is in the source code for anyone to read) AES128 key.
-
-All "ch-set" commands will default to the primary channel at index 0, but can be applied to other channels with the "ch-index" parameter:
-
-```
-meshtastic --ch-index 1 --ch-set name mychan --ch-set channel_num 4 --info
-```
-
-## Ham radio support
-
-Meshtastic is designed to be used without a radio operator license. If you do have a license you can set your operator ID and turn off encryption with:
-
-```
-meshtastic --port /dev/ttyUSB1 --set-ham KI1345
-Connected to radio
-Setting Ham ID to KI1345 and turning off encryption
-Writing modified channels to device
-```
-
-## Changing multiple settings from a yaml file
-
-You can put parameters into a yaml file to update multiple values. See the [example_config.yaml](example_config.yaml).
-
-This is how you might call it:
-
-```
-meshtastic --configure example_config.yaml
-```
-
-## FAQ/common problems
-
-This is a collection of common questions and answers from our friendly forum.
-
-### [Permission denied: ‘/dev/ttyUSB0’](https://meshtastic.discourse.group/t/question-on-permission-denied-dev-ttyusb0/590/3?u=geeksville)
-
-This indicates an OS permission problem for access by your user to the USB serial port. Typically this is fixed by the following.
-
-```
-sudo usermod -a -G dialout $USER
-```
-
-This adds the "dialout" group to your user. You'll need to obtain a new login session (for example, by logging out and logging back in) for the group change (and thus permission change) to take effect.
-
-## Mac OS Big Sur
-
-There is a problem with Big Sur and pyserial. The workaround is to install a newer version of pyserial:
-
-```
-pip3 install -U --pre pyserial
-```
-
-Afterwards you can use the Meshtastic python client again on MacOS.
-
-## A note to developers of this lib
-
-We use the visual-studio-code 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 don't change formatting on lines you haven't changed.
-
-If you need to build a new release you'll need:
-
-```
-apt install pandoc
-sudo pip3 install markdown pdoc3 webencodings pyparsing twine autopep8 pylint pytest pytest-cov
-```
-
-For development, you will probably want to run:
-
-```
-pip3 install -r requirements.txt
-```
-
-To lint, run:
-
-```
-pylint meshtastic
-```
-
-To test, first install this code locally, then run pytest:
-
-```
-pip3 install .
-pytest
-```
-
-Possible options for testing:
-
-- For more verbosity, add "-v" or even "-vv" like this:
-
-```
-pytest -vv
-```
-
-- To run just unit tests:
-
-```
-pytest
-# or (more verbosely)
-pytest -m unit
-# or
-make
-```
-
-- To run just integration tests:
-
-```
-pytest -m int
-```
-
-- To 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.
-
-- To run the smoke test with only two device connected serially (aka smoke2):
-
-```
-pytest -m smoke2
-```
-
-- To run the wifi smoke test:
-
-```
-pytest -m smokewifi
-```
-
-- To 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
-```
-
-- To add another classification of tests such as "unit" or "smoke1", see [pytest.ini](pytest.ini).
-
-- 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
-```
-
-- To see slowest unit tests, you can run:
-
-```
-pytest --durations=0
-# or
-make slow
-```
 
 [![Powered by Vercel](https://raw.githubusercontent.com/abumalick/powered-by-vercel/master/powered-by-vercel.svg)](https://vercel.com?utm_source=meshtastic&utm_campaign=oss)

bin/regen-docs.sh

@@ -1 +1,4 @@
-pdoc3 --html -f --output-dir docs meshtastic
+# Note: Docs are generated from this command below, albeit from Vercel.
+# The docs/ dir is not used and is no longer commited.
+# see sachaw if you have questions
+pdoc3 --html -f --output-dir docs meshtastic