From 41ac3924d6db7721293d8efb4eebbc34b1e13fd1 Mon Sep 17 00:00:00 2001 From: sigmahour <> Date: Sat, 1 Oct 2022 01:39:29 -0400 Subject: [PATCH 01/12] update to firmware-http-api --- docs/developers/Firmware/http-api.mdx | 56 +++++++++++++++++---------- 1 file changed, 36 insertions(+), 20 deletions(-) diff --git a/docs/developers/Firmware/http-api.mdx b/docs/developers/Firmware/http-api.mdx index e784fb0c..745571aa 100644 --- a/docs/developers/Firmware/http-api.mdx +++ b/docs/developers/Firmware/http-api.mdx @@ -17,44 +17,60 @@ This is a mini-spec on a HTTP API which can be used by browser based clients to ## Request headers -- Content-Type: application/x-protobuf -- Cookie: session=ABAD1D (this header is added automatically by the browser client, not implemented yet) +- Content-Type: `application/x-protobuf` + - Indicates Meshtatics protobufs +- Cookie: `session=ABAD1D` (not yet implemented) + - Added automatically by the browser client. ## Response headers -- Content-Type: application/x-protobuf (indicates meshtatics protobufs) -- X-Protobuf-Schema: (not required but recommended for documentation/reflection purposes) - -(not implemented) All clients (if their request did not include a session cookie) will be assigned a random and unique session key. The cookie will not be set if the client already has one. Example response: - -- Set-Cookie: session=ABAD1D;path=/ - -(FIXME - check how this relates to XSS attacks) +- Content-Type: `application/x-protobuf` + - Indicates Meshtatics protobufs +- X-Protobuf-Schema: __ + - Not required but recommended for documentation/reflection purposes +- Set-Cookie: `session=ABAD1D;path=/` (not yet implemented, consider security implications of `path=/`) + - All client requests that did not include a session cookie will be assigned a random and unique session key. The cookie will not be set if the client already has one. ## Endpoints Two endpoints are specified: -### PUT /api/v1/toradio +### /api/v1/toradio -A PUT to this endpoint will be expected to contain a series of ToRadio protobuf payloads. For the initial implementation only one ToRadio message per PUT is supported, but future optimizations to improve throughput might add support for multiple ToRadios in a single PUT. +#### PUT + +A `PUT` request to this endpoint will be expected to contain a series of ToRadio protobuf payloads. The protobufs will be sent in binary as the body for the request. -A request with OPTIONS to this endpoint will return status 204 and just the headers. +For the initial implementation, only one ToRadio message per request is supported, but future optimizations to improve throughput might add support for multiple ToRadios in a single request. -### GET /api/v1/fromradio?chunked=false|true&all=true|false +#### OPTIONS -A GET from this endpoint will return a series of FromRadio protobufs. +An `OPTIONS`request to this endpoint will return a response status code `204` and headers only. -- chunked=false|true (not implemented) - - If the query parameter "chunked" is false (or unset), the GET will simply return all the protobufs which can currently be delivered for this clients session (this would allow the client to poll by doing a series of GETs). This is the only option that is supported in the initial release. - - Eventually if chunked=true, the response will be a [stream of chunks](https://en.wikipedia.org/wiki/Chunked_transfer_encoding) that the server will keep open as long as the client wants. This will allow efficient streaming of new FromRadio protobufs as they are generated by the radio. -- all=true|false - - If this query is false (or unset), the GET will return just one protobuf. If set to true, will return all the available protobufs. +### /api/v1/fromradio + +#### GET + +A `GET` request from this endpoint will return a series of FromRadio protobufs. The protobufs will be sent in binary as the body for the request. +**Parameters** + +##### **/api/v1/fromradio?all** +- `all=false` (unset default) + - Only one protobuf is returned. +- `all=true` + - All available protobufs are returned. + +##### **/api/v1/fromradio?chunked** +- `chunked=false` (unset default, not yet implemented) + - The request returns all protobufs that can be delivered for the client's session (this would allow the client to poll by doing a series of requests). This is the only option that is supported in the initial release. +- `chunked=true` (not yet implemented) + - If chunked=true, the response will be a [stream of chunks](https://en.wikipedia.org/wiki/Chunked_transfer_encoding) that the server will keep open as long as the client wants. This will allow efficient streaming of new `FromRadio` protobufs as they are generated by the radio. + ## Authentication The initial release will not have **any** user authentication. i.e. we assume access to the HTTP server is enough to establish trust. From df57102e3e89308e645c17cee764b76b9109789d Mon Sep 17 00:00:00 2001 From: sigmahour <> Date: Sat, 1 Oct 2022 10:49:28 -0400 Subject: [PATCH 02/12] revisions to http-api --- docs/developers/Firmware/http-api.mdx | 25 +++++++++++++++---------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/docs/developers/Firmware/http-api.mdx b/docs/developers/Firmware/http-api.mdx index 745571aa..295961fd 100644 --- a/docs/developers/Firmware/http-api.mdx +++ b/docs/developers/Firmware/http-api.mdx @@ -5,7 +5,7 @@ sidebar_label: HTTP API --- :::info -This is a mini-spec on a HTTP API which can be used by browser based clients to do operations with devices. +This is a mini-spec of the HTTP REST API which can be used by browser based clients to interact with Meshtastic devices. ::: ## Why protobufs @@ -17,18 +17,19 @@ This is a mini-spec on a HTTP API which can be used by browser based clients to ## Request headers -- Content-Type: `application/x-protobuf` - - Indicates Meshtatics protobufs -- Cookie: `session=ABAD1D` (not yet implemented) +- `Content-Type: application/x-protobuf` + - Indicates protobuf content (Meshtatic protobufs) +- `Cookie: session=ABAD1D` (not yet implemented) - Added automatically by the browser client. ## Response headers -- Content-Type: `application/x-protobuf` - - Indicates Meshtatics protobufs -- X-Protobuf-Schema: __ +- `Content-Type: application/x-protobuf` + - Indicates protobuf content (Meshtatic protobufs) +- `X-Protobuf-Schema: ` - Not required but recommended for documentation/reflection purposes -- Set-Cookie: `session=ABAD1D;path=/` (not yet implemented, consider security implications of `path=/`) +- `Set-Cookie: session=ABAD1D;path=/` (not yet implemented) + - All client requests that did not include a session cookie will be assigned a random and unique session key. The cookie will not be set if the client already has one. ## Endpoints @@ -37,6 +38,8 @@ Two endpoints are specified: ### /api/v1/toradio +Allows `PUT` and `OPTION` requests. + #### PUT A `PUT` request to this endpoint will be expected to contain a series of ToRadio protobuf payloads. @@ -51,6 +54,8 @@ An `OPTIONS`request to this endpoint will return a response status code `204` an ### /api/v1/fromradio +Allows `GET` requests. + #### GET A `GET` request from this endpoint will return a series of FromRadio protobufs. @@ -73,7 +78,7 @@ The protobufs will be sent in binary as the body for the request. ## Authentication -The initial release will not have **any** user authentication. i.e. we assume access to the HTTP server is enough to establish trust. +The initial release will not have **any** user authentication. We assume access to the HTTP server is enough to establish trust. Since authentication is also eventually needed for our other transports (TCP and eventually open BLE), we will be adding authentication **in-band**. When added in the second release there will be a new payload supported inside ToRadio for `SignIn `. The server will respond with a FromRadio `SignInResponse okay|fail`. Also, in the case of the REST API, that SignIn status will then be associated with the current session key. Most (all?) ToRadio packets will be ignored if the client is not signed in. Most (all?) FromRadio packets will be sent to clients that are not signed in. @@ -83,7 +88,7 @@ Since authentication is also eventually needed for our other transports (TCP and See: -A reference client written in JavaScript will provide a JavaScript API for using this transport. That client will do HTTP connections, use the generated protobuf JavaScript code and provide an API that hides all of this REST plumbing. The two key methods will be "sendToRadio(packet) and onFromRadio(callback)". +A reference client written in JavaScript will provide a JavaScript API for using this transport. That client will do HTTP connections, use the generated protobuf JavaScript code and provide an API that hides all of this REST plumbing. The two key methods will be `sendToRadio(packet)` and `onFromRadio(callback)`. ### Protoman From 4c09fcf1932d7da1a8209ad5be0e9fe5908ee5cf Mon Sep 17 00:00:00 2001 From: sigmahour <> Date: Wed, 5 Oct 2022 23:32:07 -0400 Subject: [PATCH 03/12] revisions --- docs/developers/Firmware/http-api.mdx | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/docs/developers/Firmware/http-api.mdx b/docs/developers/Firmware/http-api.mdx index 295961fd..62ff9b60 100644 --- a/docs/developers/Firmware/http-api.mdx +++ b/docs/developers/Firmware/http-api.mdx @@ -5,7 +5,7 @@ sidebar_label: HTTP API --- :::info -This is a mini-spec of the HTTP REST API which can be used by browser based clients to interact with Meshtastic devices. +This is a mini-spec on a HTTP API which can be used by browser based clients to interact with Meshtastic devices. ::: ## Why protobufs @@ -19,8 +19,6 @@ This is a mini-spec of the HTTP REST API which can be used by browser based clie - `Content-Type: application/x-protobuf` - Indicates protobuf content (Meshtatic protobufs) -- `Cookie: session=ABAD1D` (not yet implemented) - - Added automatically by the browser client. ## Response headers @@ -28,9 +26,6 @@ This is a mini-spec of the HTTP REST API which can be used by browser based clie - Indicates protobuf content (Meshtatic protobufs) - `X-Protobuf-Schema: ` - Not required but recommended for documentation/reflection purposes -- `Set-Cookie: session=ABAD1D;path=/` (not yet implemented) - - - All client requests that did not include a session cookie will be assigned a random and unique session key. The cookie will not be set if the client already has one. ## Endpoints From ea67ce055965646982e4ff2667b5d997bc961333 Mon Sep 17 00:00:00 2001 From: sigmahour <> Date: Mon, 10 Oct 2022 13:57:39 -0400 Subject: [PATCH 04/12] updates to channel information --- docs/faq/channel.mdx | 18 +-- docs/settings/config/channels.mdx | 206 ++++++++++++++++++++++++++++++ docs/settings/config/index.mdx | 1 + 3 files changed, 208 insertions(+), 17 deletions(-) create mode 100644 docs/settings/config/channels.mdx diff --git a/docs/faq/channel.mdx b/docs/faq/channel.mdx index d6a1e99d..ff53fece 100644 --- a/docs/faq/channel.mdx +++ b/docs/faq/channel.mdx @@ -6,22 +6,6 @@ sidebar_label: Channel ## Overview -### What is a Meshtastic Channel? - -This is the LoRa channel you're broadcasting on, the modem configuration (spreading factor, bandwidth and error correction), along with a special identifier for your group, and optional encryption. - -### What is a LoRa channel? - -This is the LoRa frequency within the frequency band your device is configured to use. - ### How do I share my Meshtastic Channel with other people? -Your Meshtastic client (Android, Web, or Python) will provide you a URL or QR code. You can email, text or print this URL or QR code and share it with people you want to join your Meshtastic Channel. Note: This feature is not yet available on the iOS app. - -### What is a Primary Channel? - -This is the first channel that's created for you when you initially setup your Meshtastic Channel. - -### What is a Secondary Channel? - -As this is a new feature, secondary channels work on the device and the Python Script. Support for secondary channels by other clients is pending. +Your Meshtastic client (Android, Web, or Python) will provide you a URL or QR code. You can email, text or print this URL or QR code and share it with people you want to join your Meshtastic Channel. Note: This feature is not yet available on the iOS app. \ No newline at end of file diff --git a/docs/settings/config/channels.mdx b/docs/settings/config/channels.mdx new file mode 100644 index 00000000..87107e73 --- /dev/null +++ b/docs/settings/config/channels.mdx @@ -0,0 +1,206 @@ +--- +id: channels +title: Channel Configuration +sidebar_label: Channels +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +The Channels config options are: Index, Roles, and Settings. Channel config uses an admin message sending a `Channel` protobuf which also consists of a `ChannelSettings` protobuf. + +:::info +**Channel Settings** (as described on this page) should not be confused with [LoRa Radio Settings](/docs/settings/config/lora) + +[LoRa Radio Settings](/docs/settings/config/lora) contain the modem configuration (frequency settings, spreading factor, bandwidth, and error correction) used for the radio. These settings are identical accross all channels, can *not* be unique. These settings are directly applied to the Primary channel from which all Secondary channels derive their settings. + +**Channel Settings** contain information for segregating conversations, configuring encryption, and the ability to enable or disable messaging over internet gateways. These settings are unique per channel. +::: + +## Channel Config Values + +### Index + +The channel index begins at 0 and ends at 7 (total of 8 channels) + +_Indexing_ can not be modified. + +| Index | Channel | Default Role | Purpose | +| :--------------------: | :----------------: | :----------------: | :----------------: | +| 0 | 1 | `PRIMARY` | Used as `default` channel | +| 1 | 2 | `DISABLED` | User defined | +| 2 | 3 | `DISABLED` | User defined | +| 3 | 4 | `DISABLED` | User defined | +| 4 | 5 | `DISABLED` | User defined | +| 5 | 6 | `DISABLED` | User defined | +| 6 | 7 | `DISABLED` | User defined | +| 7 | 8 | `SECONDARY` | Used as `admin` channel | + +### Role + +Each channel is assigned one of 3 roles: + +1. `DISABLED` or `0` + - The channel is no longer available for use. + - Channel Settings are cleared. +2. `PRIMARY` or `1` + - This is the first channel that's created for you on initial setup. + - Defaults: `Index` is `0`. `ID` is `0`. `Name` is empty `""`. + - Can not be disabled. + - Only one Primary channel can exist. + - All Secondary channels derive their [Radio Settings](/docs/settings/config/lora) from this channel. + - Direct Messages are only available on this channel. +3. `SECONDARY` or `2` + - Derives its [Radio Settings](/docs/settings/config/lora) from the Primary channel. + - Can modify encryption key (psk). + +## Channel Settings Values + +If a channel is disabled, all channel settings are set to default. + +Channel settings are unique per channel and consist of: + +### ID + +Used to construct a globally unique channel ID. + +`0` by default for `default` channel. + +The full globally unique ID will be `name.id` where ID is base36 encoded. Assuming that the number of Meshtastic users is below 20K (true for a long time) the chance of this 64 bit random number colliding with anyone else is super low. The penalty for collision is low as well. + +### Name + +A short identifier (< 12 bytes) for the channel. + +Empty `""` by default for all channels. + +If this is left an empty string it is assumed that this channel is the `default` channel. + +### PSK + +Hex byte `0x01` for `default` channel. + +Must be either 0 bytes (no crypto), 16 bytes (AES128), or 32 bytes (AES256). + +### Downlink Enabled + +If enabled, messages captured from a **public** internet gateway will be forwarded to the local mesh. + +Set to `false` by default for all channels. + +### Uplink Enabled + +If enabled, messages from the mesh will be sent to the **public** internet through any node's configured gateway. + +Set to `false` by default for all channels. + + + + + +:::info +All Channel config options are available on Android. +::: + + + + + +:::info +All Channel config options are available on iOS, iPadOS and macOS. +::: + + + + + +All Channel config options are available in the python CLI. Example commands are below: + +**Id** + +```shell title="Set the PRIMARY channel ID" +meshtastic --ch-set id 1234 --ch-index 0 +``` + +**Name** + +```shell title="Set channel name for the PRIMARY channel" +meshtastic --ch-set name MyChannel --ch-index 0 +``` + +```shell title="Set channel name for the PRIMARY channel with spaces" +meshtastic --ch-set name "My Channel" --ch-index 0 +``` + +**PSK** + +If you use Meshtastic for exchanging messages you don't want other people to see, `random` is the setting you should use. Selecting a `default` or any of the `simple` values from the following table will use publicly known encryption keys. They're shipped with Meshtastic source code and thus, anyone can listen to messages encrypted by them. They're great for testing and public channels. + +| Setting | Behavior | +| :--------------------: | :-----------------------------------------------------------------------------------: | +| `none` | Disable Encryption | +| `default` | Default Encryption (use the weak encryption key) | +| `random` | Generate a secure 256-bit encryption key. Use this setting for private communication. | +| `simple0`- `simple254` | Uses a single byte encoding for encryption | + +```shell title="Set encryption to default on PRIMARY channel" +meshtastic --ch-set psk default --ch-index 0 +``` + +```shell title="Set encryption to random on PRIMARY channel" +meshtastic --ch-set psk random --ch-index 0 +``` + +```shell title="Set encryption to single byte on PRIMARY channel" +meshtastic --ch-set psk simple15 --ch-index 0 +``` + +```shell title="Set encryption to your own key on PRIMARY channel" +meshtastic --ch-set psk 0x1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b --ch-index 0 +``` + +```shell title="Disable encryption on PRIMARY channel" +meshtastic --ch-set psk none --ch-index 0 +``` + +**Uplink / Downlink** + +For configuring gateways, please see [MQTT](/docs/settings/moduleconfig/mqtt) + +```shell title="Enable/Disable Uplink on PRIMARY channel" +meshtastic --ch-set uplink_enabled true --ch-index 0 +meshtastic --ch-set uplink_enabled false --ch-index 0 +``` + +```shell title="Enable/Disable Downlink on SECONDARY channel" +meshtastic --ch-set downlink_enabled true --ch-index 1 +meshtastic --ch-set downlink_enabled false --ch-index 5 +``` + + + + + +:::info +All Channel config options are available in the Flasher. +::: + + + + + +:::info +All Channel config options are available in the Web UI. +::: + + + \ No newline at end of file diff --git a/docs/settings/config/index.mdx b/docs/settings/config/index.mdx index fe051eee..07a176f7 100644 --- a/docs/settings/config/index.mdx +++ b/docs/settings/config/index.mdx @@ -10,6 +10,7 @@ There are several config sections in the Meshtastic firmware, these are broken o | Name | Description | |:----:|:-----------:| | [Bluetooth](bluetooth) | Bluetooth config options are: Enabled, Pairing Mode and Fixed PIN. | +| [Channels](channels) | Channels config options are: Index, Role and Settings. | | [Device](device) | Device config options are: Device Role, Serial Output, Debug Log and Factory Reset. | | [Display](display) | Display config options are: Screen On Duration, Auto Carousel Interval, Always Point North, and GPS Format. | | [LoRa](lora) | The LoRa config options are: Region, Modem Preset, Max Hops, Transmit Power, Bandwidth, Spread Factor, Coding Rate, Frequency Offset, Transmit Disabled and Ignore Incoming Array. | From eb31f0f6b5de8635a90e82726638591ec22bacc2 Mon Sep 17 00:00:00 2001 From: sigmahour <> Date: Mon, 10 Oct 2022 14:09:49 -0400 Subject: [PATCH 05/12] minor updates --- docs/settings/config/channels.mdx | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/settings/config/channels.mdx b/docs/settings/config/channels.mdx index 87107e73..5e0113ef 100644 --- a/docs/settings/config/channels.mdx +++ b/docs/settings/config/channels.mdx @@ -12,9 +12,9 @@ The Channels config options are: Index, Roles, and Settings. Channel config uses :::info **Channel Settings** (as described on this page) should not be confused with [LoRa Radio Settings](/docs/settings/config/lora) -[LoRa Radio Settings](/docs/settings/config/lora) contain the modem configuration (frequency settings, spreading factor, bandwidth, and error correction) used for the radio. These settings are identical accross all channels, can *not* be unique. These settings are directly applied to the Primary channel from which all Secondary channels derive their settings. +[LoRa Radio Settings](/docs/settings/config/lora) contain the modem configuration (frequency settings, spreading factor, bandwidth, and error correction) used for the radio. These settings are identical accross all channels and can *not* be unique. These settings are directly applied to the Primary channel from which all Secondary channels derive their settings. -**Channel Settings** contain information for segregating conversations, configuring encryption, and the ability to enable or disable messaging over internet gateways. These settings are unique per channel. +**Channel Settings** contain information for segregating conversations, configuring encryption, and enabling or disabling messaging over internet gateways. These settings are unique per channel. ::: ## Channel Config Values @@ -44,8 +44,7 @@ Each channel is assigned one of 3 roles: - The channel is no longer available for use. - Channel Settings are cleared. 2. `PRIMARY` or `1` - - This is the first channel that's created for you on initial setup. - - Defaults: `Index` is `0`. `ID` is `0`. `Name` is empty `""`. + - This is the first channel that is created for you on initial setup. - Can not be disabled. - Only one Primary channel can exist. - All Secondary channels derive their [Radio Settings](/docs/settings/config/lora) from this channel. @@ -56,9 +55,7 @@ Each channel is assigned one of 3 roles: ## Channel Settings Values -If a channel is disabled, all channel settings are set to default. - -Channel settings are unique per channel and consist of: +If a channel is disabled, all channel settings are set to default. Channel settings are unique per channel and consist of: ### ID @@ -78,6 +75,8 @@ If this is left an empty string it is assumed that this channel is the `default` ### PSK +The encryption key used for private channels. + Hex byte `0x01` for `default` channel. Must be either 0 bytes (no crypto), 16 bytes (AES128), or 32 bytes (AES256). From 2e50d10549ae830dea1d9dbbd9955e345e9119ac Mon Sep 17 00:00:00 2001 From: sigmahour <> Date: Mon, 10 Oct 2022 16:20:50 -0400 Subject: [PATCH 06/12] minor changes --- docs/settings/config/channels.mdx | 33 +++++++++++++++---------------- 1 file changed, 16 insertions(+), 17 deletions(-) diff --git a/docs/settings/config/channels.mdx b/docs/settings/config/channels.mdx index 5e0113ef..a613cdb0 100644 --- a/docs/settings/config/channels.mdx +++ b/docs/settings/config/channels.mdx @@ -12,16 +12,16 @@ The Channels config options are: Index, Roles, and Settings. Channel config uses :::info **Channel Settings** (as described on this page) should not be confused with [LoRa Radio Settings](/docs/settings/config/lora) -[LoRa Radio Settings](/docs/settings/config/lora) contain the modem configuration (frequency settings, spreading factor, bandwidth, and error correction) used for the radio. These settings are identical accross all channels and can *not* be unique. These settings are directly applied to the Primary channel from which all Secondary channels derive their settings. +[LoRa Radio Settings](/docs/settings/config/lora) contain the modem configuration (frequency settings, spreading factor, bandwidth, etc.) used for the radio. These settings are identical for all channels and can *not* be unique per channel. Radio settings are directly applied to the Primary channel from which all Secondary channels derive their radio settings. -**Channel Settings** contain information for segregating conversations, configuring encryption, and enabling or disabling messaging over internet gateways. These settings are unique per channel. +**Channel Settings** contain information for segregating message groups, configuring optional encryption, and enabling or disabling messaging over internet gateways. These settings *are* unique and configurable per channel. ::: ## Channel Config Values ### Index -The channel index begins at 0 and ends at 7 (total of 8 channels) +The channel index begins at 0 and ends at 7. _Indexing_ can not be modified. @@ -40,18 +40,18 @@ _Indexing_ can not be modified. Each channel is assigned one of 3 roles: -1. `DISABLED` or `0` - - The channel is no longer available for use. - - Channel Settings are cleared. -2. `PRIMARY` or `1` +1. `PRIMARY` or `1` - This is the first channel that is created for you on initial setup. - Can not be disabled. - - Only one Primary channel can exist. - - All Secondary channels derive their [Radio Settings](/docs/settings/config/lora) from this channel. - - Direct Messages are only available on this channel. -3. `SECONDARY` or `2` - - Derives its [Radio Settings](/docs/settings/config/lora) from the Primary channel. - - Can modify encryption key (psk). + - Only one primary channel can exist. + - All secondary channels derive their [Radio Settings](/docs/settings/config/lora) from this channel. + - Direct messages are only available on this channel. +2. `SECONDARY` or `2` + - Derives its [Radio Settings](/docs/settings/config/lora) from the primary channel. + - Can modify the encryption key (psk). +3. `DISABLED` or `0` + - The channel is no longer available for use. + - Channel Settings are cleared. ## Channel Settings Values @@ -133,16 +133,15 @@ meshtastic --ch-set id 1234 --ch-index 0 **Name** ```shell title="Set channel name for the PRIMARY channel" +# without spaces meshtastic --ch-set name MyChannel --ch-index 0 -``` - -```shell title="Set channel name for the PRIMARY channel with spaces" +# with spaces meshtastic --ch-set name "My Channel" --ch-index 0 ``` **PSK** -If you use Meshtastic for exchanging messages you don't want other people to see, `random` is the setting you should use. Selecting a `default` or any of the `simple` values from the following table will use publicly known encryption keys. They're shipped with Meshtastic source code and thus, anyone can listen to messages encrypted by them. They're great for testing and public channels. +If you use Meshtastic for exchanging messages you don't want other people to see, `random` is the setting you should use. Selecting `default` or any of the `simple` values from the following table will use publicly known encryption keys. They're shipped with Meshtastic source code and thus, anyone can listen to messages encrypted by them. They're great for testing and public channels. | Setting | Behavior | | :--------------------: | :-----------------------------------------------------------------------------------: | From 4905644599f33f14cfde7e207ae79d3e59277eb7 Mon Sep 17 00:00:00 2001 From: sigmahour <> Date: Tue, 11 Oct 2022 11:47:48 -0400 Subject: [PATCH 07/12] changes made per review --- docs/settings/config/channels.mdx | 27 +++++++++++++++++---------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/docs/settings/config/channels.mdx b/docs/settings/config/channels.mdx index a613cdb0..41d36e94 100644 --- a/docs/settings/config/channels.mdx +++ b/docs/settings/config/channels.mdx @@ -10,11 +10,11 @@ import TabItem from '@theme/TabItem'; The Channels config options are: Index, Roles, and Settings. Channel config uses an admin message sending a `Channel` protobuf which also consists of a `ChannelSettings` protobuf. :::info -**Channel Settings** (as described on this page) should not be confused with [LoRa Radio Settings](/docs/settings/config/lora) +**Channel Settings** (as described on this page) should not be confused with [Modem Preset Settings](/docs/settings/config/lora#modem-preset) -[LoRa Radio Settings](/docs/settings/config/lora) contain the modem configuration (frequency settings, spreading factor, bandwidth, etc.) used for the radio. These settings are identical for all channels and can *not* be unique per channel. Radio settings are directly applied to the Primary channel from which all Secondary channels derive their radio settings. +[Modem Preset Settings](/docs/settings/config/lora#modem-preset) contain the modem configuration (frequency settings, spreading factor, bandwidth, etc.) used for the LoRa radio. These settings are identical for all channels and can **not** be unique per channel. Modem settings are directly applied to the Primary channel from which all Secondary channels derive their modem settings. -**Channel Settings** contain information for segregating message groups, configuring optional encryption, and enabling or disabling messaging over internet gateways. These settings *are* unique and configurable per channel. +**Channel Settings** contain information for segregating message groups, configuring optional encryption, and enabling or disabling messaging over internet gateways. These settings **are** unique and configurable per channel. ::: ## Channel Config Values @@ -34,7 +34,12 @@ _Indexing_ can not be modified. | 4 | 5 | `DISABLED` | User defined | | 5 | 6 | `DISABLED` | User defined | | 6 | 7 | `DISABLED` | User defined | -| 7 | 8 | `SECONDARY` | Used as `admin` channel | +| 7 | 8 | `DISABLED` | User defined | + +:::note +You can **not** have `DISABLED` channels inbetween active channels such as `PRIMARY` and `SECONDARY`. Active channels must be consecutive. +::: + ### Role @@ -44,14 +49,14 @@ Each channel is assigned one of 3 roles: - This is the first channel that is created for you on initial setup. - Can not be disabled. - Only one primary channel can exist. - - All secondary channels derive their [Radio Settings](/docs/settings/config/lora) from this channel. + - All secondary channels derive their [Modem Presets](/docs/settings/config/lora#modem-preset) from this channel. - Direct messages are only available on this channel. 2. `SECONDARY` or `2` - - Derives its [Radio Settings](/docs/settings/config/lora) from the primary channel. + - Derives its [Modem Preset](/docs/settings/config/lora#modem-preset) from the primary channel. - Can modify the encryption key (psk). 3. `DISABLED` or `0` - The channel is no longer available for use. - - Channel Settings are cleared. + - Channel settings are cleared. ## Channel Settings Values @@ -67,11 +72,13 @@ The full globally unique ID will be `name.id` where ID is base36 encoded. Assumi ### Name -A short identifier (< 12 bytes) for the channel. +A short identifier _(< 12 bytes)_ for the channel. -Empty `""` by default for all channels. +| Reserved Name | Purpose | +| :--------------------: | :----------------: | +| `""` (default) | If left empty on the primary channel, this designates the `default` channel. | +| `admin` | On Secondary channels, the name `admin` (case sensitive) designates the `admin` channel used to administer nodes over the mesh | -If this is left an empty string it is assumed that this channel is the `default` channel. ### PSK From 7a23c701b08a82f45196c7917cfa986b56aa67fb Mon Sep 17 00:00:00 2001 From: sigmahour <> Date: Tue, 11 Oct 2022 12:12:44 -0400 Subject: [PATCH 08/12] removed modem setting info from channel roles --- docs/settings/config/channels.mdx | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/settings/config/channels.mdx b/docs/settings/config/channels.mdx index 41d36e94..ae786880 100644 --- a/docs/settings/config/channels.mdx +++ b/docs/settings/config/channels.mdx @@ -12,7 +12,7 @@ The Channels config options are: Index, Roles, and Settings. Channel config uses :::info **Channel Settings** (as described on this page) should not be confused with [Modem Preset Settings](/docs/settings/config/lora#modem-preset) -[Modem Preset Settings](/docs/settings/config/lora#modem-preset) contain the modem configuration (frequency settings, spreading factor, bandwidth, etc.) used for the LoRa radio. These settings are identical for all channels and can **not** be unique per channel. Modem settings are directly applied to the Primary channel from which all Secondary channels derive their modem settings. +[Modem Preset Settings](/docs/settings/config/lora#modem-preset) contain the modem configuration (frequency settings, spreading factor, bandwidth, etc.) used for the LoRa radio. These settings are identical for all channels and can **not** be unique per channel. **Channel Settings** contain information for segregating message groups, configuring optional encryption, and enabling or disabling messaging over internet gateways. These settings **are** unique and configurable per channel. ::: @@ -40,7 +40,6 @@ _Indexing_ can not be modified. You can **not** have `DISABLED` channels inbetween active channels such as `PRIMARY` and `SECONDARY`. Active channels must be consecutive. ::: - ### Role Each channel is assigned one of 3 roles: @@ -49,10 +48,8 @@ Each channel is assigned one of 3 roles: - This is the first channel that is created for you on initial setup. - Can not be disabled. - Only one primary channel can exist. - - All secondary channels derive their [Modem Presets](/docs/settings/config/lora#modem-preset) from this channel. - Direct messages are only available on this channel. 2. `SECONDARY` or `2` - - Derives its [Modem Preset](/docs/settings/config/lora#modem-preset) from the primary channel. - Can modify the encryption key (psk). 3. `DISABLED` or `0` - The channel is no longer available for use. @@ -72,14 +69,13 @@ The full globally unique ID will be `name.id` where ID is base36 encoded. Assumi ### Name -A short identifier _(< 12 bytes)_ for the channel. +A short identifier for the channel. _(< 12 bytes)_ | Reserved Name | Purpose | | :--------------------: | :----------------: | | `""` (default) | If left empty on the primary channel, this designates the `default` channel. | | `admin` | On Secondary channels, the name `admin` (case sensitive) designates the `admin` channel used to administer nodes over the mesh | - ### PSK The encryption key used for private channels. From 94b054a216072c5038906a6baea5cdece697bcfa Mon Sep 17 00:00:00 2001 From: sigmahour <> Date: Tue, 11 Oct 2022 12:20:29 -0400 Subject: [PATCH 09/12] minor changes --- docs/settings/config/channels.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/settings/config/channels.mdx b/docs/settings/config/channels.mdx index ae786880..aea4e2ef 100644 --- a/docs/settings/config/channels.mdx +++ b/docs/settings/config/channels.mdx @@ -57,7 +57,9 @@ Each channel is assigned one of 3 roles: ## Channel Settings Values -If a channel is disabled, all channel settings are set to default. Channel settings are unique per channel and consist of: +The Channel Settings options are: ID, Name, PSK, Downlink Enabled, and Uplink Enabled. Channel settings are embeded in the `Channel` protobuf as a `ChannelSettings` protobuf and sent as an admin message. + +If a channel is disabled, all channel settings are set to default. ### ID From 17379a0a337a8360d1a3ff00ae8a290e1da104b1 Mon Sep 17 00:00:00 2001 From: sigmahour <> Date: Tue, 11 Oct 2022 12:28:42 -0400 Subject: [PATCH 10/12] more minor changes --- docs/settings/config/channels.mdx | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/settings/config/channels.mdx b/docs/settings/config/channels.mdx index aea4e2ef..96582767 100644 --- a/docs/settings/config/channels.mdx +++ b/docs/settings/config/channels.mdx @@ -46,28 +46,27 @@ Each channel is assigned one of 3 roles: 1. `PRIMARY` or `1` - This is the first channel that is created for you on initial setup. - - Can not be disabled. - - Only one primary channel can exist. + - Only one primary channel can exist and can not be disabled. - Direct messages are only available on this channel. 2. `SECONDARY` or `2` - Can modify the encryption key (psk). 3. `DISABLED` or `0` - The channel is no longer available for use. - - Channel settings are cleared. + - All channel settings are set to default. ## Channel Settings Values The Channel Settings options are: ID, Name, PSK, Downlink Enabled, and Uplink Enabled. Channel settings are embeded in the `Channel` protobuf as a `ChannelSettings` protobuf and sent as an admin message. -If a channel is disabled, all channel settings are set to default. - ### ID Used to construct a globally unique channel ID. `0` by default for `default` channel. -The full globally unique ID will be `name.id` where ID is base36 encoded. Assuming that the number of Meshtastic users is below 20K (true for a long time) the chance of this 64 bit random number colliding with anyone else is super low. The penalty for collision is low as well. +:::note +The full globally unique ID will be `.` where ID is base36 encoded. Assuming that the number of Meshtastic users is below 20K (true for a long time) the chance of this 64 bit random number colliding with anyone else is super low. The penalty for collision is low as well. +::: ### Name From 1797911ccc30b99003054bdf2c1e6403a6ddda61 Mon Sep 17 00:00:00 2001 From: sigmahour <> Date: Tue, 11 Oct 2022 13:07:35 -0400 Subject: [PATCH 11/12] minor changes --- docs/settings/config/channels.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/settings/config/channels.mdx b/docs/settings/config/channels.mdx index 96582767..bcbebb6d 100644 --- a/docs/settings/config/channels.mdx +++ b/docs/settings/config/channels.mdx @@ -52,21 +52,21 @@ Each channel is assigned one of 3 roles: - Can modify the encryption key (psk). 3. `DISABLED` or `0` - The channel is no longer available for use. - - All channel settings are set to default. + - The channel settings are set to default. ## Channel Settings Values The Channel Settings options are: ID, Name, PSK, Downlink Enabled, and Uplink Enabled. Channel settings are embeded in the `Channel` protobuf as a `ChannelSettings` protobuf and sent as an admin message. +:::note +The full globally unique ID will be constructed with the Name and ID (`.`) where ID is base36 encoded. Assuming that the number of Meshtastic users is below 20K (true for a long time) the chance of this 64 bit random number colliding with anyone else is super low. The penalty for collision is low as well. +::: + ### ID Used to construct a globally unique channel ID. -`0` by default for `default` channel. - -:::note -The full globally unique ID will be `.` where ID is base36 encoded. Assuming that the number of Meshtastic users is below 20K (true for a long time) the chance of this 64 bit random number colliding with anyone else is super low. The penalty for collision is low as well. -::: +Set to `0` by default. ### Name From d9636ee481a3e126f7fcca58f361603a9a03b562 Mon Sep 17 00:00:00 2001 From: sigmahour <> Date: Tue, 11 Oct 2022 14:23:35 -0400 Subject: [PATCH 12/12] update --- docs/settings/config/channels.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/settings/config/channels.mdx b/docs/settings/config/channels.mdx index bcbebb6d..5875c3be 100644 --- a/docs/settings/config/channels.mdx +++ b/docs/settings/config/channels.mdx @@ -59,7 +59,7 @@ Each channel is assigned one of 3 roles: The Channel Settings options are: ID, Name, PSK, Downlink Enabled, and Uplink Enabled. Channel settings are embeded in the `Channel` protobuf as a `ChannelSettings` protobuf and sent as an admin message. :::note -The full globally unique ID will be constructed with the Name and ID (`.`) where ID is base36 encoded. Assuming that the number of Meshtastic users is below 20K (true for a long time) the chance of this 64 bit random number colliding with anyone else is super low. The penalty for collision is low as well. +The full globally unique ID will be constructed from the Name and ID (`.`) where ID is base36 encoded. Assuming that the number of Meshtastic users is below 20K (true for a long time) the chance of this 64 bit random number colliding with anyone else is super low. The penalty for collision is low as well. ::: ### ID @@ -74,14 +74,14 @@ A short identifier for the channel. _(< 12 bytes)_ | Reserved Name | Purpose | | :--------------------: | :----------------: | -| `""` (default) | If left empty on the primary channel, this designates the `default` channel. | +| `""` (default) | If left empty on the Primary channel, this designates the `default` channel. | | `admin` | On Secondary channels, the name `admin` (case sensitive) designates the `admin` channel used to administer nodes over the mesh | ### PSK The encryption key used for private channels. -Hex byte `0x01` for `default` channel. +Hex byte `0x01` for the Primary `default` channel. Must be either 0 bytes (no crypto), 16 bytes (AES128), or 32 bytes (AES256).