mirror of
https://github.com/meshtastic/meshtastic.git
synced 2024-11-15 18:14:19 -08:00
b397d84eac
* docs: --noproto needs a physical connection * docs: --noproto caveats without admonitions * docs: --noproto caveats using consistent language
239 lines
9.5 KiB
Plaintext
239 lines
9.5 KiB
Plaintext
---
|
||
id: usage
|
||
title: Using the Meshtastic CLI
|
||
sidebar_label: Usage
|
||
slug: /software/python/cli/usage
|
||
sidebar_position: 2
|
||
---
|
||
|
||
This section covers using the "meshtastic" command line executable, which displays packets sent over the network as JSON and lets you see serial debugging information from the Meshtastic devices.
|
||
|
||
:::note
|
||
The `meshtastic` command is not run within python but is a script run from your operating system shell prompt. When you type "meshtastic" and the prompt is unable to find the command in Windows, check that the python "scripts" directory [is in your path](https://datatofish.com/add-python-to-windows-path).
|
||
:::
|
||
|
||
## Viewing Serial Output
|
||
|
||
The `--noproto` command in the Meshtastic Python CLI is used to disable the API and function merely as a "dumb serial terminal." This mode of operation allows both the API and device functionalities to remain accessible for regular use, while simultaneously providing a window into the raw serial output. This feature can be particularly useful for debugging, development, or understanding the low-level communication between devices. Depends on a physically cabled serial connection. It will connect but not display information over a network (--host) or Bluetooth (--ble) connection.
|
||
|
||
```shellsession title="Example Usage"
|
||
user@host % meshtastic --noproto
|
||
# You should see results similar to this:
|
||
WARNING file:mesh_interface.py _sendToRadio line:681 Not sending packet because protocol use is disabled by noProto
|
||
Connected to radio
|
||
WARNING file:mesh_interface.py _sendPacket line:531 Not sending packet because protocol use is disabled by noProto
|
||
INFO | 18:38:04 711 [DeviceTelemetryModule] (Sending): air_util_tx=0.116361, channel_utilization=1.916667, battery_level=101, voltage=4.171000
|
||
DEBUG | 18:38:04 711 [DeviceTelemetryModule] updateTelemetry LOCAL
|
||
DEBUG | 18:38:04 711 [DeviceTelemetryModule] Node status update: 2 online, 4 total
|
||
INFO | 18:38:04 711 [DeviceTelemetryModule] Sending packet to phone
|
||
INFO | 18:38:04 711 Telling client we have new packets 28
|
||
```
|
||
|
||
## Getting a list of User Preferences
|
||
|
||
You can get a list of user preferences by running '--get' with an invalid attribute such as 'all'.
|
||
|
||
```shell
|
||
meshtastic --get all
|
||
```
|
||
|
||
## Changing 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 protocol from your phone will reset this timer)
|
||
|
||
```shell title="Expected Output"
|
||
# You should see a result similar to this:
|
||
mydir$ meshtastic --set power.wait_bluetooth_secs 28800
|
||
Connected to radio...
|
||
Setting power.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.
|
||
|
||
```shell
|
||
meshtastic --setlat 25.2 --setlon -16.8 --setalt 120
|
||
```
|
||
|
||
Or to configure an ESP32 based board to join a Wifi network as a station:
|
||
|
||
```shell
|
||
meshtastic --set network.wifi_ssid mywifissid --set network.wifi_psk mywifipsw --set network.wifi_enabled 1
|
||
```
|
||
|
||
:::note
|
||
For a full list of preferences which can be set (and their documentation) can be found in the [protobufs](https://buf.build/meshtastic/protobufs/docs/main:meshtastic#meshtastic.User).
|
||
:::
|
||
|
||
### Changing channel settings
|
||
|
||
The channel settings can also be changed, either by using a standard (shareable) meshtastic URL or you can set a particular channel parameter (for advanced users).
|
||
|
||
:::warning
|
||
Meshtastic encodes the radio channel and PSK in the channel's URL. All nodes must connect to the channel again by using the URL provided after a change in this section by performing the `--info` switch.
|
||
:::
|
||
|
||
```shell
|
||
meshtastic --ch-set name mychan --ch-index 1 --info
|
||
```
|
||
|
||
You can even set the channel preshared key to a particular AES128 or AES256 sequence.
|
||
|
||
```shell
|
||
meshtastic --ch-index 1 --ch-set psk 0x1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b --info
|
||
```
|
||
|
||
Use `--ch-set psk none --ch-index 0` to turn off encryption.
|
||
|
||
Use `--ch-set psk random --ch-index 0` to 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 --ch-index 0` to restore the standard 'default' (minimally secure, because it is in the source code for anyone to read) AES128 key.
|
||
|
||
Use `--ch-set psk base64:{key} --ch-index {index}` to set the PSK of a channel to a known entity
|
||
|
||
All `ch-set` commands need to have the `ch-index` parameter specified:
|
||
|
||
```shell
|
||
meshtastic --ch-index 1 --ch-set name mychan --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:
|
||
|
||
```shell title="Expected Output"
|
||
# You should see a result similar to this:
|
||
mydir$ meshtastic --set-ham KI1345
|
||
Connected to radio
|
||
Setting Ham ID to KI1345 and turning off encryption
|
||
Writing modified channels to device
|
||
```
|
||
|
||
Toggling `set-ham` changes your device settings in the following ways.
|
||
|
||
| Setting | `set-ham` Default | Normal Default |
|
||
| :----------: | :---------------: | :------------------------------------------------------------------------: |
|
||
| `IsLicensed` | `true` | See [User Config - IsLicensed](/docs/configuration/radio/user#is-licensed-ham) |
|
||
| `LongName` | _Your CallSign_ | See [User Config - LongName](/docs/configuration/radio/user#long-name) |
|
||
| `ShortName` | _Abrv CallSign_ | See [User Config - ShortName](/docs/configuration/radio/user#short-name) |
|
||
| `PSK` | `""` | See [Channel Settings - PSK](#changing-the-preshared-key) |
|
||
|
||
## Changing the preshared key
|
||
|
||
You can set the channel preshared key to a particular AES128 or AES256 sequence.
|
||
|
||
```shell
|
||
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.
|
||
|
||
## Utilizing BLE via the Python CLI
|
||
|
||
The Python CLI supports communicating with Meshtastic devices via Bluetooth Low Energy (BLE), in addition to the standard serial and TCP/IP connections. To use BLE, you will need a Bluetooth adapter on your computer.
|
||
|
||
### Scan for BLE Devices
|
||
|
||
First, you can scan for available Meshtastic devices using:
|
||
|
||
```shell
|
||
meshtastic --ble-scan
|
||
```
|
||
|
||
This will list all Meshtastic devices discoverable over BLE along with their addresses and names in the following format:
|
||
|
||
```shell
|
||
Found: name='Meshtastic_1234' address='AA11BB22-CC33-DD44-EE55-FF6677889900'
|
||
BLE scan finished
|
||
```
|
||
|
||
### Available Commands
|
||
|
||
Once you have the device address or name, you can utilize it alongside your normal Python CLI commands like `--info`, `--nodes`, `--export-config`, etc. but with the `--ble` option to communicate via BLE rather than serial.
|
||
|
||
You can use **either** the name or address to issue your commands.
|
||
|
||
```shell
|
||
meshtastic --ble <name> --info
|
||
meshtastic --ble <address> --nodes
|
||
```
|
||
|
||
The initial time you use the `--ble` option for a specific device, you will be prompted to enter the BLE PIN code (as is normal with a client). Once paired, this step won't be required unless you forget the device.
|
||
|
||
:::note
|
||
On Linux, you may need to pair the BLE device using `bluetoothctl` before connecting. This allows entering the required PIN for pairing.
|
||
:::
|
||
|
||
### Additional BLE Examples
|
||
|
||
#### Scan for devices and get info from the first one:
|
||
|
||
```bash
|
||
meshtastic --ble-scan
|
||
# Sample output:
|
||
# Found: name='Meshtastic_1234' address='AA11BB22-CC33-DD44-EE55-FF6677889900'
|
||
# Found: name='Meshtastic_5678' address='FF00DD00-AA11-BB22-CC33-DD44EE5566FF'
|
||
BLE scan finished
|
||
|
||
meshtastic --ble AA11BB22-CC33-DD44-EE55-FF6677889900 --info
|
||
```
|
||
|
||
#### Connect to a named device and read the node list:
|
||
|
||
```shell
|
||
meshtastic --ble Meshtastic_1234 --nodes
|
||
```
|
||
#### Export device config with --export-config
|
||
|
||
```shell
|
||
meshtastic --ble Meshtastic_1234 --export-config > config.yaml
|
||
```
|
||
|
||
#### Send a command to a remote device using the --dest option:
|
||
|
||
```shell
|
||
meshtastic --dest '!fe1932db4' --set device.is_managed false --ble Meshtastic_9abc
|
||
```
|
||
|
||
#### For debugging, you can enable verbose BLE logging by adding the `--debug` flag:
|
||
|
||
```shell
|
||
meshtastic --ble AA11BB22-CC33-DD44-EE55-FF6677889900 --debug --info
|
||
```
|
||
|
||
## FAQ/common problems
|
||
|
||
This is a collection of common questions and answers from our friendly forum.
|
||
|
||
### Permission denied: ‘/dev/ttyUSB0’
|
||
|
||
As previously discussed on the [forum](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.
|
||
|
||
```shell
|
||
sudo usermod -a -G dialout <username>
|
||
```
|
||
|
||
If adding your user to the dialout group does not work, you can use the following command to find out which group to add your user to.
|
||
In this example (from Arch Linux) the group was "uucp"
|
||
|
||
```shell
|
||
❯ ls -al /dev/ttyACM0
|
||
crw-rw---- 1 root uucp 166, 0 Jul 20 21:52 /dev/ttyACM0
|
||
```
|
||
|
||
### Mac OS Big Sur
|
||
|
||
There is a problem with Big Sur and pyserial. The workaround is to install a newer version of pyserial:
|
||
|
||
```shell
|
||
pip3 install -U --pre pyserial
|
||
``` |