meshtastic/docs/software/linux-native.mdx

95 lines
3.6 KiB
Plaintext
Raw Normal View History

---
2022-11-02 11:46:54 -07:00
id: linux-native
title: Linux Native Application
sidebar_label: Linux Native
2024-01-24 21:30:50 -08:00
sidebar_position: 5
---
2022-10-31 00:45:47 -07:00
The device software can also run on a native Linux machine thanks to the [Portduino framework](https://github.com/geeksville/framework-portduino).
2022-10-31 00:45:47 -07:00
The application either simulates some of the interfaces, or uses the real hardware of your machine.
Device firmware from 1.3.42 and on even allows you to simulate the LoRa chip by sending and receiving Meshtastic packets via a local TCP port.
In this way, you can let multiple instances of the application communicate with each other as if they did via LoRa.
For instructions on how to use it, see the [interactive simulator](https://github.com/GUVWAF/Meshtasticator/blob/master/INTERACTIVE_SIM.md) that also emulates a wireless environment using simulated positions of the nodes.
2023-01-19 05:01:57 -08:00
## Usage with a Linux machine
2022-10-31 00:45:47 -07:00
The easiest way of building the native application is using Visual Studio Code with the PlatformIO extension.
2022-11-02 11:46:54 -07:00
See the instructions for creating such a building environment [here](/docs/development/firmware/build).
2022-10-31 00:45:47 -07:00
Then after opening the firmware repository in Visual Studio Code, simply click on the PlatformIO extension in the left bar, select native and click on 'Build'.
This will generate the binary file 'program' which you can find in `.pio/build/native/`.
Once in this directory or when you copied the file to your current directory, launch the application with `./program`.
2022-10-31 00:45:47 -07:00
Additional arguments can be given to the program, which are listed as follows:
- `-d DIRECTORY`: The directory to use as the virtual filesystem (VFS).
- `-e`: Erase the virtual filesystem before use.
- `-h MAC_ADDRESS`: The MAC address to assign to this virtual machine.
- `-p TCP_PORT`: The local TCP port to use for running the Meshtastic API.
2023-01-19 05:01:57 -08:00
## Usage with Docker
If you do not own a Linux machine, or you just want to separate things, you might want
2022-10-31 00:45:47 -07:00
to run the application inside a docker container.
### The Image
To build docker image, type
`docker build -t meshtastic/device .`
### Usage
To run a container, type
`docker run --rm -p 4403:4403 meshtastic/device`
or, to get an interactive shell on the docker created container:
`docker run -it -p 4403:4403 meshtastic/device bash`
You might want to mount your local development folder:
2022-10-31 00:45:47 -07:00
firmware
`docker run -it --mount type=bind,source=/PathToMyProjects/Meshtastic/Meshtastic-device-mybranch,target=/Meshtastic-device-mybranch -p 4403:4403 meshtastic/device bash`
### Build the native application
Linux native application should be built inside the container.
For this you must run container with interactive console
"-it", as seen above.
First, some environment variables need to be set up with command:
`. ~/.platformio/penv/bin/activate`
You can build amd64 image with command
`./bin/build-native.sh`
### Executing the application interactively
The built binary file should be found under name
`release/latest/bins/universal/meshtastic_linux_amd64`.
If this is not the case, you can also use the direct program name:
`.pio/build/native/program`
To use Python CLI against exposed TCP port 4403,
type this in the host machine:
`meshtastic --info --host localhost`
While you can interact with it in the same way as a normal device using a client that supports TCP connections, the application has its limitations. For example, rebooting is not implemented, so for some settings to apply you have to restart the application.
### Stop the container
Run this to get the ID:
`docker ps`
Stop the container with command:
`docker kill <id>`
> Tip: you can just use the first few characters of the ID in docker commands