mirror of
https://github.com/meshtastic/meshtastic.git
synced 2024-11-14 17:44:37 -08:00
239 lines
8.6 KiB
Plaintext
239 lines
8.6 KiB
Plaintext
---
|
|
id: installation
|
|
title: Meshtastic Python CLI installation
|
|
sidebar_label: Installation
|
|
slug: /software/python/cli/installation
|
|
sidebar_position: 1
|
|
description: This page offers comprehensive instructions on methods of installing the Meshtastic Python CLI across different operating systems.
|
|
---
|
|
|
|
import Tabs from "@theme/Tabs";
|
|
import TabItem from "@theme/TabItem";
|
|
|
|
## Meshtastic Python Library
|
|
|
|
This library provides a command-line interface (CLI) for managing the user settings of Meshtastic nodes and provides an easy API for sending and receiving messages over mesh radios. Events are delivered using a publish-subscribe model, and you can subscribe to only the message types you are interested in.
|
|
|
|
The [Meshtastic-python repo](https://github.com/meshtastic/Meshtastic-python) is an excellent source of information. If you wish to view the code or contribute to the development of the Python library or the command-line interface, please visit the Meshtastic Python [GitHub page](https://github.com/meshtastic/Meshtastic-python).
|
|
|
|
### Prerequisites
|
|
|
|
Before installing, ensure that your system meets the following requirements:
|
|
|
|
- **Serial Drivers**: Your computer should have the required serial drivers installed for the [CP210X USB to UART bridge](https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers) or the [CH9102](http://www.wch.cn/downloads/CH343SER_ZIP.html) (for some newer boards).
|
|
- **Python**: Python 3 should be installed on your system. Check with `python3 -V` and install it if necessary.
|
|
- **pip**: The Python package installer pip should be installed. Check with `pip3 -V` and install it if necessary.
|
|
|
|
After ensuring the requirements are met, follow the installation instructions for your operating system in the tabbed section below.
|
|
|
|
### Installation Instructions
|
|
|
|
To install the Meshtastic CLI, select the tab for your operating system and follow the step-by-step instructions for installing via `pip`. For Ubuntu only, you can alternatively install the [Standalone version](#standalone-installation-ubuntu-only) if you prefer.
|
|
|
|
<Tabs
|
|
groupId="operating-system"
|
|
queryString="install-python-cli"
|
|
defaultValue="windows"
|
|
values={[
|
|
{label: 'Linux', value: 'linux'},
|
|
{label: 'macOS', value: 'macos'},
|
|
{label: 'Windows', value: 'windows'},
|
|
{label: 'Termux for Android', value: 'termux'},
|
|
]}>
|
|
<TabItem value="linux">
|
|
|
|
#### Linux
|
|
|
|
- Check that your computer has the required serial drivers installed
|
|
|
|
- Connect your Meshtastic device to your USB port
|
|
- Use the command
|
|
```shell
|
|
lsusb
|
|
```
|
|
- You should see something like:
|
|
- `ID 10c4:ea60 Silicon Labs CP210x UART Bridge` for CP210X
|
|
- `ID 1a86:55d4 QinHeng Electronics USB Single Serial` for CH9102
|
|
- If there is no seral device shown that matches the device you are using, please review our [Install Serial Drivers](/docs/getting-started/serial-drivers/) page before proceeding.
|
|
|
|
- Check that your computer has Python 3 installed.
|
|
|
|
- Use the command
|
|
```shell
|
|
python3 -V
|
|
```
|
|
- If this does not return a version, install python
|
|
```shell
|
|
sudo apt-get update
|
|
sudo apt-get install python3
|
|
```
|
|
|
|
- Pip is typically installed if you are using python 3 version >= 3.4
|
|
|
|
- Check that pip is installed using this command
|
|
```shell
|
|
pip3 -V
|
|
```
|
|
- If this does not return a version, install pip
|
|
```shell
|
|
sudo apt-get install python3-pip
|
|
```
|
|
|
|
- Optional: use a python virtual environment (otherwise jump to step "Install pytap2")
|
|
- Install python-virtualenvwrapper (arch based distros as an example)
|
|
```shell
|
|
sudo pacman -Syu python-virtualenvwrapper
|
|
```
|
|
- Create a virtual environment
|
|
```shell
|
|
source /usr/bin/virtualenvwrapper.sh
|
|
mkvirtualenv meshtastic
|
|
workon meshtastic
|
|
```
|
|
- Install pytap2
|
|
```shell
|
|
pip3 install --upgrade pytap2
|
|
```
|
|
- Install meshtastic:
|
|
```shell
|
|
pip3 install --upgrade meshtastic
|
|
```
|
|
- Using pipx as an alternative to pip3 if `externally-managed-environment` error is encountered
|
|
```shell
|
|
sudo apt install pipx && pipx install meshtastic
|
|
```
|
|
- If using `pipx` it may be necessary to update `$PATH` by running:
|
|
```shell
|
|
pipx ensurepath
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="macos">
|
|
|
|
#### macOS
|
|
|
|
- Check that your computer has the required serial drivers installed
|
|
- Connect your Meshtastic device to your USB port
|
|
- Navigate to `Apple Menu > About This Mac > System Report... > Hardware > USB`
|
|
- You should see something like `CP210X USB to UART Bridge Controller`
|
|
- If there is no serial device shown that matches the device you are using, please review our [Install Serial Drivers](/docs/getting-started/serial-drivers/) page before proceeding.
|
|
- Check that your computer has Python 3 installed.
|
|
- Use the command
|
|
```shell
|
|
python3 -V
|
|
```
|
|
- If this does not return a version, install [python](https://www.python.org)
|
|
- The following uses Homebrew to install `python3` which includes `pip3`.
|
|
- Check if you have Homebrew installed with the following command
|
|
```shell
|
|
brew -v
|
|
```
|
|
If it's not installed, follow the instructions on the [Homebrew website](https://brew.sh) before continuing.
|
|
- Install Python3
|
|
```shell
|
|
brew install python3
|
|
```
|
|
- Pip is typically installed if you are using python 3 version >= 3.4
|
|
|
|
- Check that pip is installed using this command
|
|
```shell
|
|
pip3 -V
|
|
```
|
|
- If this does not return a version, install [pip](https://pip.pypa.io/en/stable/installing)
|
|
|
|
- Install pytap2
|
|
```shell
|
|
sudo pip3 install --upgrade pytap2
|
|
```
|
|
- Install meshtastic:
|
|
```shell
|
|
sudo pip3 install --upgrade meshtastic
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="windows">
|
|
|
|
#### Windows
|
|
|
|
- Check that your computer has the required serial drivers installed
|
|
- Connect your Meshtastic device to your USB port
|
|
- Open Device Manager
|
|
- Under `Ports (COM & LPT)` you should see something like `Silicon Labs CP210X USB to UART Bridge (COM5)`
|
|
- If there is no serial device shown that matches the device you are using, please review our [Install Serial Drivers](/docs/getting-started/serial-drivers/) page before proceeding.
|
|
- Check that your computer has Python 3 installed.
|
|
- Use the command
|
|
```powershell
|
|
py -V
|
|
```
|
|
- If this does not return a version, install [python](https://www.python.org)
|
|
|
|
:::info
|
|
When installing Python, make sure to select the option to "Add Python to PATH" or check the box that says "Add Python to environment variables". If you missed this during installation, you can add Python to your system's PATH manually after installation. Failing to do so may result in errors when trying to use Python or pip commands.
|
|
:::
|
|
|
|
- Pip is typically installed if you are using python 3 version >= 3.4
|
|
- Check that pip is installed using this command
|
|
```powershell
|
|
pip3 -V
|
|
```
|
|
- If this does not return a version, install [pip](https://pip.pypa.io/en/stable/installing)
|
|
- Install pytap2
|
|
```powershell
|
|
pip3 install --upgrade pytap2
|
|
```
|
|
- Install meshtastic:
|
|
```powershell
|
|
pip3 install --upgrade meshtastic
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="termux">
|
|
|
|
#### Termux
|
|
|
|
- Install [Termux from F-Droid](https://f-droid.org/en/packages/com.termux) or [Github Releases](https://github.com/termux/termux-app/releases). The Google Play store version has been deprecated.
|
|
- Load Termux and update the package list
|
|
```shell
|
|
pkg update
|
|
```
|
|
- Upgrade the installed packages
|
|
```shell
|
|
pkg upgrade
|
|
```
|
|
- Install python
|
|
```shell
|
|
pkg install python
|
|
```
|
|
- Upgrade pip and installed meshtastic and some of its dependencies
|
|
```shell
|
|
pip install --upgrade pip pygatt pytap2 wheel meshtastic
|
|
```
|
|
|
|
:::note
|
|
Be aware that the Meshtastic CLI is not able to control the nodes over USB through termux, but you can control devices over Wifi using the `--host x.x.x.x` option with the device IP address (ESP32 or Pico W only). Wifi connection is currently under development and may not be working properly just yet. If you would like to provide feedback or test this feature, please visit our [forum](https://meshtastic.discourse.group) or join our [Discord server](https://discord.gg/ktMAKGBnBs) for more information.
|
|
:::
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
**You may need to close and re-open the CLI. The path variables may or may not update for the current session when installing.**
|
|
|
|
|
|
### Standalone Installation (Ubuntu only)
|
|
|
|
1. Download the `meshtastic_ubuntu` executable from the [Releases](https://github.com/meshtastic/Meshtastic-python/releases) page.
|
|
2. Run the following command to make the file executable and rename it `meshtastic`:
|
|
|
|
```shell
|
|
chmod +x meshtastic_ubuntu && mv meshtastic_ubuntu meshtastic
|
|
```
|
|
3. To run the CLI:
|
|
|
|
```shell
|
|
./meshtastic
|
|
```
|
|
|
|
:::tip
|
|
Copy (or move) this binary somewhere in your path.
|
|
:::
|