mirror of
https://github.com/meshtastic/meshtastic.git
synced 2025-02-02 08:42:11 -08:00
Consolidate firmware and build instructions
This commit is contained in:
Sacha Weatherstone
parent
16a4f3386d
commit
57913a2564
|
|
@ -1,66 +0,0 @@
|
|||
If you have not already done so, download and have the latest firmware for your device, and flash it to your device.
|
||||
|
||||
There is a very good guide for doing this [here](https://github.com/meshtastic/Meshtastic-device#firmware-installation).
|
||||
|
||||
Part of this guide covers the installation of pip which must be done first.
|
||||
|
||||
**For Linux users:**
|
||||
From a terminal copy and paste the following command
|
||||
```bash
|
||||
pip3 install meshtastic
|
||||
```
|
||||
|
||||
**For Windows users:**
|
||||
_Insert instructions on how to install meshtastic here_
|
||||
|
||||
**For Mac OS users:**
|
||||
_Insert instructions on how to install meshtastic here_
|
||||
|
||||
Using a text editor, open a blank document and copy and paste the following text
|
||||
|
||||
```bash
|
||||
#/bin/sh
|
||||
clear
|
||||
echo "Set all Router Parameter"
|
||||
meshtastic --setowner MeshRelay
|
||||
meshtastic --settime
|
||||
meshtastic --set is_router true
|
||||
meshtastic --setlat 53.9 --setlon -6.8 --setalt 91
|
||||
meshtastic –info
|
||||
```
|
||||
|
||||
Alter the parameter `meshtastic --setowner MeshRelay` and change "MeshRelay" to your chosen name
|
||||
This will set the name of the relay.
|
||||
|
||||
Alter the parameter `meshtastic --setlat 53.9 --setlon -6.8 --setalt 91`
|
||||
|
||||
This parameter sets the latitude, longitude and altitude of your relay, assuming it doesn’t have a working or installed GPS. If you have a working GPS, the device will connect to a GPS satellite and update the latitude, longitude and altitude.
|
||||
|
||||
Using this site, find the location of where you plan to place your relay.
|
||||
[Get latitude, longitude and altitude](https://www.maps.ie/coordinates.html)
|
||||
|
||||
Move the place marker over the spot where your relay is to placed, and it will give you the latitude, longitude and altitude.
|
||||
|
||||
Enter the latitude and longitude to one decimal place and altitude is recorded in meters in the configuration file.
|
||||
|
||||
As a suggestion, save the configuration file into the same folder, where you have downloaded the latest device firmware.
|
||||
Save the file as `relay.sh`
|
||||
|
||||
Go to the folder where you have saved the script and right click on "Open in Terminal"
|
||||
At the command prompt in Terminal, enter the following command
|
||||
|
||||
```bash
|
||||
sudo chmod -R 777 relay.sh
|
||||
```
|
||||
|
||||
This enables the script to be executed as a program.
|
||||
|
||||
Then at the prompt enter: `./relay.sh`
|
||||
|
||||
That's it, your Meshtastic device is now configure to operate as a relay.
|
||||
|
||||
**Some explanations of other parameters**
|
||||
|
||||
`meshtastic --set is_router true` tells node to be power conscious and to only power up the screen/BLE if the user presses a button. Eventually will also imply that "this node has good line of sight and should be heavily weighted when routing". This is the option you should probably use.
|
||||
|
||||
`meshtastic --set is_low_power true`. This option means "work like a regular node, with the normal sleep/wake pattern but even though you see power coming in on USB don’t constantly stay awake". You **almost certainly don't want this option** but it is useful for some edge cases (solar powered node that still talks Bluetooth to the app etc...).
|
||||
|
|
@ -49,7 +49,7 @@ This layer is conventional non-reliable LoRa packet transmission. The transmitte
|
|||
|
||||
- **Packet Header - Unique ID:** The ID is a large, 32 bit ID to ensure there is enough unique state to protect an encrypted payload from attack.
|
||||
|
||||
- **Payload:** An encrypted and packed protobuf encoding of the SubPacket protobuf. Only the SubPacket is encrypted, while headers are not. This allows the option of eventually allowing nodes to route packets without knowing anything about the encrypted payload. For more information, see the [encryption](/docs/developers/device/encryption) and [protobufs](/docs/developers/protobufs/api) documentation. Any data past the maximum length is truncated.
|
||||
- **Payload:** An encrypted and packed protobuf encoding of the SubPacket protobuf. Only the SubPacket is encrypted, while headers are not. This allows the option of eventually allowing nodes to route packets without knowing anything about the encrypted payload. For more information, see the [encryption](/docs/developers/firmware/encryption) and [protobufs](/docs/developers/protobufs/api) documentation. Any data past the maximum length is truncated.
|
||||
|
||||
#### Collision Avoidance
|
||||
|
||||
|
|
@ -48,7 +48,7 @@ A number of [key services](http://github.com/meshtastic/meshtastic-device/tree/m
|
|||
|
||||
The easiest way to get started is:
|
||||
|
||||
- [Build and install](/docs/software/other/build-instructions) the standard codebase from GitHub.
|
||||
- [Build and install](/docs/developers/firmware/build-env) the standard codebase from GitHub.
|
||||
- Copy [src/modules/ReplyModule.\*](http://github.com/meshtastic/meshtastic-device/tree/master/src/modules/ReplyModule.cpp) into src/modules/YourModule.*. Then change the port number from *PortNum_REPLY_APP* to *PortNum_PRIVATE_APP\*.
|
||||
- Edit moduless/Moduless.cpp:setupModules() to add a call to create an instance of your module (see comment at head of that function)
|
||||
- Rebuild with your new messaging goodness and install on the device
|
||||
|
|
@ -72,7 +72,7 @@ If you are making a new app using meshtastic, please send in a pull request to a
|
|||
- **0-63** Core Meshtastic use; do not use for third party apps
|
||||
- **64-127** Registered 3rd party apps. Send in a pull request that adds a new entry to portnums.proto to register your application
|
||||
- **256-511** Use one of these portnums for your private applications that you don't want to register publicly
|
||||
- **1024-66559** Are reserved for use by IP tunneling (see [here](/docs/developers/device/portnum) for more information)
|
||||
- **1024-66559** Are reserved for use by IP tunneling (see [here](/docs/developers/firmware/portnum) for more information)
|
||||
|
||||
All other values are reserved.
|
||||
|
||||
34
docs/developers/firmware/stacktrace-decode.md
Normal file
34
docs/developers/firmware/stacktrace-decode.md
Normal file
|
|
@ -0,0 +1,34 @@
|
|||
---
|
||||
id: build-env
|
||||
title: Creating a build environment
|
||||
sidebar_label: Building Meshtastic
|
||||
---
|
||||
|
||||
You may encounter a situation where your device crashes and are left with a stacktrace, below are two methods of decoding them.
|
||||
|
||||
## Manual
|
||||
|
||||
First save the backtrace string to a text file:
|
||||
|
||||
:::info
|
||||
This method uses the symbols of the `firmware.elf` file generated from your latest build, you may wish to rebuild to get up-to-date symbols.
|
||||
:::
|
||||
|
||||
```title="backtrace.txt"
|
||||
[...]
|
||||
Backtrace: 0x....
|
||||
```
|
||||
|
||||
Now run the exception decoder:
|
||||
|
||||
```bash
|
||||
bin/exception_decoder.py backtrace.txt
|
||||
```
|
||||
|
||||
## Real Time
|
||||
|
||||
In order to decode stack traces in real time, kep the following command (replacing `DEVICE_PORT` with your device's port) running in your terminal with the suspect device connected
|
||||
|
||||
```bash
|
||||
pio device monitor --port DEVICE_PORT -f esp32_exception_decoder
|
||||
```
|
||||
|
|
@ -16,4 +16,4 @@ A list of available modules is available [here](/docs/software/modules).
|
|||
|
||||
### I'd like to write a module. How do I get started?
|
||||
|
||||
API documentation for creating modules is available [here](/docs/developers/device/module-api).
|
||||
API documentation for creating modules is available [here](/docs/developers/firmware/module-api).
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ slug: /legal
|
|||
This project is still pretty young but moving at a pretty good pace. Not all features are fully implemented in the current alpha builds.
|
||||
|
||||
- We don't make these devices and they haven't been tested by UL or the FCC. If you use them, you are experimenting and we can't promise they won't burn your house down ;-)
|
||||
- The encryption implementation is good but see this list of [caveats](/docs/developers/device/encryption#summary-of-strengthsweaknesses-of-our-current-implementation) to determine risks you might face.
|
||||
- The encryption implementation is good but see this list of [caveats](/docs/developers/firmware/encryption#summary-of-strengthsweaknesses-of-our-current-implementation) to determine risks you might face.
|
||||
|
||||
## Legal FAQ
|
||||
|
||||
|
|
|
|||
|
|
@ -291,7 +291,7 @@ Initial Requirements:
|
|||
|
||||
### Meshtastic channel configuration
|
||||
|
||||
Don't use this on the "Long Range / Slow" or "Long Range / Fast" channel settings. You're welcome to try and report back, but those channels have a [very low bitrate](/docs/developers/device/radio-settings#pre-defined).
|
||||
Don't use this on the "Long Range / Slow" or "Long Range / Fast" channel settings. You're welcome to try and report back, but those channels have a [very low bitrate](/docs/developers/firmware/radio-settings#pre-defined).
|
||||
|
||||
Either use a custom channel configuration with at an at least 1kbit data rate or use "Medium Range / Fast".
|
||||
|
||||
|
|
|
|||
|
|
@ -24,7 +24,7 @@ If it is helpful, [here](/docs/software/android/android-usage) is a slightly sta
|
|||
|
||||
When the user has the LoRa device in their pocket occasionally (every 15 minutes ish), the Android sister app background service will acquire the GPS position and provide it to the LoRa [firmware](https://github.com/meshtastic/Meshtastic-device). Without background location access, this core (the primary feature) of our app would not work (because you wouldn't be able to see the last known position of the hikers/skiers/users in your group).
|
||||
|
||||
This location is shared only over an [encrypted](/docs/developers/device/encryption) link and each group of users has their own AES256 key for their 'channel'. Our privacy policy is [here](/docs/legal/privacy).
|
||||
This location is shared only over an [encrypted](/docs/developers/firmware/encryption) link and each group of users has their own AES256 key for their 'channel'. Our privacy policy is [here](/docs/legal/privacy).
|
||||
|
||||
(This description has been simplified a bit: This project works with a [variety](/docs/hardware) of LoRa devices, some of which have their own built-in GPS. For the devices that have a GPS built-in, we do not use Android to get the user's location)
|
||||
|
||||
|
|
|
|||
|
|
@ -35,7 +35,7 @@ Initial Requirements:
|
|||
|
||||
### Meshtastic channel configuration
|
||||
|
||||
Don't use this on the "Long Range / Slow" or "Long Range / Fast" channel settings. You're welcome to try and report back, but those channels have a [very low bitrate](/docs/developers/device/radio-settings#pre-defined).
|
||||
Don't use this on the "Long Range / Slow" or "Long Range / Fast" channel settings. You're welcome to try and report back, but those channels have a [very low bitrate](/docs/developers/firmware/radio-settings#pre-defined).
|
||||
|
||||
Either use a custom channel configuration with at an at least 1kbit data rate or use "Medium Range / Fast".
|
||||
|
||||
|
|
|
|||
|
|
@ -1,63 +0,0 @@
|
|||
---
|
||||
id: build-instructions
|
||||
title: Build Instructions
|
||||
sidebar_label: Building
|
||||
---
|
||||
|
||||
This project uses the simple PlatformIO build system. PlatformIO is an extension to Microsoft VSCode. Workflows from building from the GUI or from the command line are listed below.
|
||||
|
||||
If you encounter any problems, please post a question in [our forum](https://meshtastic.discourse.group). And when you learn a fix, update these instructions for the next person (i.e. edit this file and send in a [pull-request](https://opensource.com/article/19/7/create-pull-request-github) which we will eagerly merge).
|
||||
|
||||
## GUI
|
||||
|
||||
1. Purchase a suitable [radio](/docs/hardware).
|
||||
2. Install [Python](https://www.python.org/downloads).
|
||||
3. Install [Git](https://git-scm.com/downloads).
|
||||
4. Reboot your computer.
|
||||
5. Install [PlatformIO](https://platformio.org/platformio-ide).
|
||||
6. Click the PlatformIO icon on the side bar. 
|
||||
7. Under `Quick Access, Miscellaneous, Clone Git Project` enter the URL of the Meshtastic repo found [here](https://github.com/meshtastic/Meshtastic-device). 
|
||||
8. Select a file location to save the repo.
|
||||
9. Once loaded, open the `platformio.ini` file.
|
||||
10. At the line `default_envs` you can change it to the board type you are building for ie. `tlora-v2, tlora-v1, tlora-v2-1-1.6, tbeam, heltec, tbeam0.7` (boards are listed further down in the file).
|
||||
11. The hardware can be configured for different countries by adding a definition to the `configuration.h` file. `#define HW_VERSION_US` or `HW_VERSION_EU433, HW_VERSION_EU865, HW_VERSION_CN, HW_VERSION_JP`. Other country settings can be found in `MeshRadio.h`. The default is `HW_VERSION_US`.
|
||||
12. Click the PlatformIO icon on the side bar. Under `Project Tasks` you can now build or upload.
|
||||
|
||||
Note - To get a clean build you may have to delete the auto-generated file `./.vscode/c_cpp_properties.json`, close and re-open Visual Studio and WAIT until the file is auto-generated before compiling again.
|
||||
|
||||
## Command Line
|
||||
|
||||
1. Purchase a suitable [radio](/docs/hardware).
|
||||
2. Install [PlatformIO](https://platformio.org/platformio-ide)
|
||||
3. Download this git repo and cd into it:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/meshtastic/Meshtastic-device.git
|
||||
cd Meshtastic-device
|
||||
```
|
||||
|
||||
4. Run `git submodule update --init --recursive` to pull in dependencies this project needs.
|
||||
5. If you are outside the USA, run `export COUNTRY=EU865` (or whatever) to set the correct frequency range for your country. Options are provided for `EU433`, `EU865`, `CN`, `JP` and `US` (default). Pull-requests eagerly accepted for other countries.
|
||||
6. Plug the radio into your USB port.
|
||||
7. Type `pio run --environment XXX -t upload` (This command will fetch dependencies, build the project and install it on the board via USB). For XXX, use the board type you have (either `tlora-v2, tlora-v1, tlora-v2-1-1.6, tbeam, heltec, tbeam0.7`).
|
||||
8. PlatformIO also installs a very nice VisualStudio Code based IDE, see their [tutorial](https://docs.platformio.org/en/latest/tutorials/espressif32/arduino_debugging_unit_testing.html) if you'd like to use it.
|
||||
|
||||
## Decoding stack traces
|
||||
|
||||
### Option 1
|
||||
|
||||
If you get a crash, you can decode the addresses from the `Backtrace:` line:
|
||||
|
||||
1. Save the `Backtrace: 0x....` line to a file, e.g., `backtrace.txt`.
|
||||
2. Run `bin/exception_decoder.py backtrace.txt` (this uses symbols from the
|
||||
last `firmware.elf`, so you must be running the same binary that's still in
|
||||
your `.pio/build` directory).
|
||||
|
||||
### Option 2
|
||||
|
||||
You can run the exception decoder to monitor the serial output and decode backtraces in real time.
|
||||
|
||||
1. From within PlatformIO, open a new terminal.
|
||||
2. At the terminal, enter:
|
||||
`pio device monitor --port /dev/cu.SLAB_USBtoUART -f esp32_exception_decoder`
|
||||
Replace the value of port with the location of your serial port.
|
||||
|
|
@ -109,7 +109,7 @@ FIXME - explain this more, talk about how useful for users and security domains.
|
|||
|
||||
## On device API
|
||||
|
||||
For information on the related on-device API see [here](/docs/developers/device/device-api).
|
||||
For information on the related on-device API see [here](/docs/developers/firmware/device-api).
|
||||
|
||||
## MQTT transport
|
||||
|
||||
|
|
|
|||
|
|
@ -6,10 +6,10 @@ sidebar_label: Software Design
|
|||
|
||||
This is a mini design doc for developing the meshtastic software.
|
||||
|
||||
- [Build instructions](build-instructions.md)
|
||||
- [On device module API](/docs/developers/device/module-api) - a tutorial on how to write small modules which run on the device and can message other nodes.
|
||||
- [Build instructions](/docs/developers/firmware/build-env)
|
||||
- [On device module API](/docs/developers/firmware/module-api) - a tutorial on how to write small modules which run on the device and can message other nodes.
|
||||
- Our [project board](https://github.com/orgs/meshtastic/projects/1) - shows what things we are currently working on and remaining work items for the current release.
|
||||
- [Power Management](power.md)
|
||||
- [Mesh algorithm](/docs/developers/device/mesh-alg)
|
||||
- [External client API](/docs/developers/device/device-api) and porting guide for new clients (iOS, python, etc...)
|
||||
- [Mesh algorithm](/docs/developers/firmware/mesh-alg)
|
||||
- [External client API](/docs/developers/firmware/device-api) and porting guide for new clients (iOS, python, etc...)
|
||||
- TODO: how to port the device code to a new device.
|
||||
|
|
|
|||
|
|
@ -53,7 +53,7 @@ Requires: [Python](https://www.python.org) and [esptool.py](https://github.com/e
|
|||
|
||||
### Visual Studio & PlatformIO
|
||||
|
||||
There is also the method of using the Visual Studio IDE. This requires having Visual Studio and PlatformIO installed, along with having cloned the meshtastic-device code as per the [build instructions](/docs/software/other/build-instructions). After loading the project in Visual Studio, select the PlatformIO alien icon, then find the appropriate device, and then click the Erase Flash command.
|
||||
There is also the method of using the Visual Studio IDE. This requires having Visual Studio and PlatformIO installed, along with having cloned the meshtastic-device code as per the [build instructions](/docs/developers/firmware/build-env). After loading the project in Visual Studio, select the PlatformIO alien icon, then find the appropriate device, and then click the Erase Flash command.
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
21
sidebars.js
21
sidebars.js
|
|
@ -124,7 +124,6 @@ module.exports = {
|
|||
"software/other/mqtt",
|
||||
"software/other/install-OSX",
|
||||
"software/other/esp32-arduino-build",
|
||||
"software/other/build-instructions",
|
||||
"software/other/ant",
|
||||
],
|
||||
},
|
||||
|
|
@ -230,18 +229,18 @@ module.exports = {
|
|||
Protobufs: ["developers/protobufs/api"],
|
||||
},
|
||||
"developers/api",
|
||||
"developers/build-env",
|
||||
"developers/publish",
|
||||
{
|
||||
Device: [
|
||||
"developers/device/device-api",
|
||||
"developers/device/radio-settings",
|
||||
"developers/device/mesh-alg",
|
||||
"developers/device/encryption",
|
||||
"developers/device/portnum",
|
||||
"developers/device/module-api",
|
||||
"developers/device/http-api",
|
||||
"developers/device/documents",
|
||||
Firmware: [
|
||||
"developers/firmware/build-env",
|
||||
"developers/firmware/device-api",
|
||||
"developers/firmware/radio-settings",
|
||||
"developers/firmware/mesh-alg",
|
||||
"developers/firmware/encryption",
|
||||
"developers/firmware/portnum",
|
||||
"developers/firmware/module-api",
|
||||
"developers/firmware/http-api",
|
||||
"developers/firmware/documents",
|
||||
],
|
||||
},
|
||||
{
|
||||
|
|
|
|||
Loading…
Reference in a new issue