From c514ada9980d80d20386276785441c7f954c3464 Mon Sep 17 00:00:00 2001 From: GUVWAF Date: Sun, 9 Oct 2022 14:55:27 +0200 Subject: [PATCH] Rename 'Docker' to 'Linux native application' And adapt the content accordingly --- docs/software/other/docker.mdx | 78 --------------- .../other/linux-native-application.mdx | 98 +++++++++++++++++++ 2 files changed, 98 insertions(+), 78 deletions(-) delete mode 100644 docs/software/other/docker.mdx create mode 100644 docs/software/other/linux-native-application.mdx diff --git a/docs/software/other/docker.mdx b/docs/software/other/docker.mdx deleted file mode 100644 index d3f3fd25..00000000 --- a/docs/software/other/docker.mdx +++ /dev/null @@ -1,78 +0,0 @@ ---- -id: docker -title: Docker -sidebar_label: Docker ---- - -## What is Docker used for - -Developers can simulate Device hardware by compiling and running -a linux native binary application. If you do not own a Linux -machine, or you just want to separate things, you might want -to run simulator 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: - -`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 also want to make some adjustments in the bin/build-all.sh to conform the amd64 build: - -``` - sed -i 's/^BOARDS_ESP32.*/BOARDS_ESP32=""/' bin/build-all.sh - sed -i 's/^BOARDS_NRF52.*/BOARDS_NRF52=""/' bin/build-all.sh - sed -i 's/echo "Building SPIFFS.*/exit/' bin/build-all.sh -``` - -You can build amd64 image with command - -`bin/build-all.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 direct program name: -`.pio/build/native/program` - -To use python cli against exposed port 4403, -type this in the host machine: - -`meshtastic --info --host localhost` - -## Stop the container - -Run this to get the ID: - -`docker ps` - -Stop the container with command: - -`docker kill ` - -> Tip: you can just use the first few characters of the ID in docker commands diff --git a/docs/software/other/linux-native-application.mdx b/docs/software/other/linux-native-application.mdx new file mode 100644 index 00000000..512d6f8d --- /dev/null +++ b/docs/software/other/linux-native-application.mdx @@ -0,0 +1,98 @@ +--- +id: linux-native-application +title: Linux native application +sidebar_label: Linux native application +--- + +The device software can also run on a native Linux machine thanks to the [Portduino framework](https://github.com/geeksville/framework-portduino). +See either [Usage with a Linux machine](#usage-with-a-linux-machine) or [Usage with Docker](#usage-with-docker) for instructions to run it. + +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. + +## Usage with a Linux machine {#usage-with-a-linux-machine} +The easiest way of building the native application is using Visual Studio Code with the PlatformIO extension. +See the instructions for creating such a building environment [here](/docs/developers/Firmware/build). + +Then after opening the Meshtastic-device 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`. + +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. + +## Usage with Docker {#usage-with-docker} + +If you do not own a Linux machine, or you just want to separate things, you might want +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: + +`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 also want to make some adjustments in the bin/build-all.sh to conform the amd64 build: + +``` + sed -i 's/^BOARDS_ESP32.*/BOARDS_ESP32=""/' bin/build-all.sh + sed -i 's/^BOARDS_NRF52.*/BOARDS_NRF52=""/' bin/build-all.sh + sed -i 's/echo "Building SPIFFS.*/exit/' bin/build-all.sh +``` + +You can build amd64 image with command + +`bin/build-all.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` + +### Stop the container + +Run this to get the ID: + +`docker ps` + +Stop the container with command: + +`docker kill ` + +> Tip: you can just use the first few characters of the ID in docker commands