meshtastic/docs/settings/modules/telemetry-module.mdx

500 lines
14 KiB
Plaintext
Raw Normal View History

---
2022-03-09 12:43:13 -08:00
id: telemetry-module
2022-06-25 00:39:41 -07:00
title: Environmental Measurement Plugin Settings
sidebar_label: Environmental Measurement Plugin
---
2021-05-05 09:18:44 -07:00
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
2022-02-23 05:24:55 -08:00
:::warning
GPIO access is fundamentally dangerous because invalid options can physically damage or destroy your hardware. Ensure that you fully understand the schematic for your particular device before trying this as we do not offer a warranty. Use at your own risk.
:::
2022-01-28 14:53:32 -08:00
:::note
2022-06-25 00:39:41 -07:00
The environment metrics feature of this plugin requires attaching a peripheral accessory to your device. It will not work without one.
2022-01-28 14:53:32 -08:00
:::
## Overview
2022-06-25 00:39:41 -07:00
In addition to key device metrics such as battery level, the Environment Monitoring Plugin will also allow nodes to send environmental metrics from externally connected sensors. Currently supported sensors are BME280, BME680, DHT11, DHT12, DHT21, DHT22, Dallas 1-wire DS18B20 and MCP9808.
2022-01-28 10:11:19 -08:00
:::tip
2022-06-25 00:39:41 -07:00
Once plugin settings are changed, a **reset** is required for them to take effect.
2022-01-27 13:53:53 -08:00
:::
## Settings
2022-04-01 14:07:46 -07:00
| Setting | Acceptable Values | Default |
| :-----------------------------------------------------: | :-----------------: | :-----: |
2022-06-25 00:39:41 -07:00
| environmental_measurement_plugin_device_update_interval | `integer` (seconds) | `0` |
| environmental_measurement_plugin_display_fahrenheit | `true`, `false` | `false` |
| environmental_measurement_plugin_measurement_enabled | `true`, `false` | `false` |
| environmental_measurement_plugin_read_error_count_threshold | `integer` | `0` |
| environmental_measurement_plugin_recovery_interval | `integer` (seconds) | `0` |
| environmental_measurement_plugin_screen_enabled | `true`, `false` | `0` |
| environmental_measurement_plugin_sensor_pin | `integer` | `0` |
| environmental_measurement_plugin_sensor_type | `0-6` | `0` |
| environmental_measurement_plugin_update_interval | `integer` (seconds) | `0` |
### environmental_measurement_plugin_device_update_interval
Interval in seconds of how often we should try to send our measurements to the mesh.
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
2022-06-25 00:39:41 -07:00
```shell title="Set plugin update interval to default"
meshtastic --set environmental_measurement_plugin_device_update_interval 0
```
2022-04-01 14:07:46 -07:00
2022-06-25 00:39:41 -07:00
```shell title="Set plugin update interval to 120 seconds"
meshtastic --set environmental_measurement_plugin_device_update_interval 120
```
</TabItem>
<TabItem value="android">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="iOS">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="web">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
</Tabs>
2022-06-25 00:39:41 -07:00
### environmental_measurement_plugin_display_fahrenheit
2022-03-30 19:37:43 -07:00
2022-02-02 11:46:12 -08:00
The sensor is always read in Celsius, but the user can opt to view the temperature display in Fahrenheit using this setting.
2021-05-03 13:11:24 -07:00
2022-02-02 11:46:12 -08:00
#### Display Farenheit/Celsius
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
2021-05-03 13:11:24 -07:00
```shell title="Display Farenheit"
2022-06-25 00:39:41 -07:00
meshtastic --set environmental_measurement_plugin_display_fahrenheit true
2022-04-01 14:07:46 -07:00
````
```shell title="Display Celsius"
2022-06-25 00:39:41 -07:00
meshtastic --set environmental_measurement_plugin_display_fahrenheit false
```
2022-02-02 11:46:12 -08:00
</TabItem>
<TabItem value="android">
2021-05-03 13:11:24 -07:00
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
2022-01-27 13:53:53 -08:00
:::
</TabItem>
<TabItem value="iOS">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
2021-05-03 15:25:24 -07:00
</TabItem>
<TabItem value="web">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
</Tabs>
2022-06-25 00:39:41 -07:00
### environmental_measurement_plugin_measurement_enabled
2022-06-25 00:39:41 -07:00
Enables the plugin to utilize environmental metrics.
2021-05-04 08:41:13 -07:00
2022-06-25 00:39:41 -07:00
#### Enable/Disable the plugin
2021-05-04 08:41:13 -07:00
2021-05-05 09:18:44 -07:00
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
2022-06-25 00:39:41 -07:00
```shell title="Enable Plugin"
meshtastic --set environmental_measurement_plugin_measurement_enabled true
2022-04-01 14:07:46 -07:00
````
2022-06-25 00:39:41 -07:00
```shell title="Disable Plugin"
meshtastic --set environmental_measurement_plugin_measurement_enabled false
2022-01-27 13:52:04 -08:00
```
2022-01-27 13:52:04 -08:00
</TabItem>
<TabItem value="android">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
2022-01-27 13:52:04 -08:00
</TabItem>
<TabItem value="iOS">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
2022-01-27 13:52:04 -08:00
</TabItem>
<TabItem value="web">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
2022-01-27 13:52:04 -08:00
</TabItem>
</Tabs>
2022-06-25 00:39:41 -07:00
### environmental_measurement_plugin_read_error_count_threshold
Sometimes sensor reads can fail. If this happens, we will retry a configurable number of attempts. Each attempt will be delayed by the minimum required refresh rate for that sensor
2022-06-25 00:39:41 -07:00
#### Configure environmental_measurement_plugin_read_error_count_threshold
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
2022-06-25 00:39:41 -07:00
```shell title="Configure environmental_measurement_plugin_read_error_count_threshold to 3 tries"
meshtastic --set environmental_measurement_plugin_read_error_count_threshold 3
2022-04-01 14:07:46 -07:00
````
</TabItem>
<TabItem value="android">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="iOS">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="web">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
</Tabs>
2022-06-25 00:39:41 -07:00
### environmental_measurement_plugin_recovery_interval
Sometimes we can end up with more than read_error_count_threshold failures. In this case, we will stop trying to read from the sensor for a while. Wait this long until trying to read from the sensor again.
2022-06-25 00:39:41 -07:00
#### Configure environmental_measurement_plugin_recovery_interval
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
2022-06-25 00:39:41 -07:00
```shell title="Configure environmental_measurement_plugin_recovery_interval to 120 seconds"
meshtastic --set environmental_measurement_plugin_recovery_interval 120
2022-04-01 14:07:46 -07:00
````
</TabItem>
<TabItem value="android">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="iOS">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="web">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
</Tabs>
2022-06-25 00:39:41 -07:00
### environmental_measurement_plugin_screen_enabled
2022-06-25 00:39:41 -07:00
Enable/Disable the Environmental Measurement Plugin on-device display.
2022-06-25 00:39:41 -07:00
#### Enable/Disable the plugin on device screen
2022-01-27 13:52:04 -08:00
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
2022-01-27 13:52:04 -08:00
```shell title="Enable on device screen"
2022-06-25 00:39:41 -07:00
meshtastic --set environmental_measurement_plugin_screen_enabled true
2022-04-01 14:07:46 -07:00
````
```shell title="Disable on device screen"
2022-06-25 00:39:41 -07:00
meshtastic --set environmental_measurement_plugin_screen_enabled false
2022-01-27 13:52:04 -08:00
```
2022-01-27 13:52:04 -08:00
</TabItem>
<TabItem value="android">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
2022-01-27 13:52:04 -08:00
</TabItem>
<TabItem value="iOS">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
2022-01-27 13:52:04 -08:00
</TabItem>
<TabItem value="web">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
2022-01-27 13:52:04 -08:00
</TabItem>
</Tabs>
2022-06-25 00:39:41 -07:00
### environmental_measurement_plugin_sensor_pin
:::note
2022-06-25 00:39:41 -07:00
The preferred setup is using I2C, so the `environmental_measurement_plugin_sensor_pin` may not be needed.
:::
Specify the preferred GPIO Pin for sensor readings. May not be needed if using I2C.
2022-02-23 05:29:05 -08:00
:::caution
To prevent damaging your device, double check your device's schematics before attaching to the GPIO pins and setting this value.
:::
2022-06-25 00:39:41 -07:00
#### Set plugin sensor pin
2022-01-27 13:52:04 -08:00
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
2022-06-25 00:39:41 -07:00
```shell title="Set plugin sensor pin"
meshtastic --set environmental_measurement_plugin_sensor_pin PINNUMBER
2022-04-01 14:07:46 -07:00
````
2022-01-27 13:52:04 -08:00
</TabItem>
<TabItem value="android">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
2022-01-27 13:52:04 -08:00
</TabItem>
<TabItem value="iOS">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
2022-01-27 13:52:04 -08:00
</TabItem>
<TabItem value="web">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
2022-01-27 13:52:04 -08:00
</TabItem>
</Tabs>
2022-06-25 00:39:41 -07:00
### environmental_measurement_plugin_sensor_type
Specify the sensor type.
2022-03-31 19:06:11 -07:00
:::important
The sensor values changed between 1.2 and 1.3. The docs represent the 1.3 values. When configuring devices on 1.2, please subtract 1 from the numbers below for the appropriate sensor.
:::
| Value | Description | Sensor Features |
| :---: | :---------------------: | :--------------------------------------: |
2022-03-31 18:42:18 -07:00
| `1` | DHT11 | Temperature, Humidity |
| `2` | DS18B20 (Dallas 1-wire) | Temperature |
| `3` | DHT12 | Temperature, Humidity |
| `4` | DHT21 | Temperature, Humidity |
| `5` | DHT22 | Temperature, Humidity |
| `6` | BME280 | Temperature, Humidity, Pressure |
| `7` | BME680 | Temperature, Humidity, Pressure, VOC Gas |
| `8` | MCP9808 | Precision Temperature |
#### Set sensor type
2022-03-31 19:06:11 -07:00
:::important
2022-03-31 19:07:59 -07:00
The sensor values changed between 1.2 and 1.3. The docs represent the 1.3 values. When configuring devices on 1.2, please subtract 1 from the numbers on the table above for the appropriate sensor.
2022-03-31 19:06:11 -07:00
:::
2022-01-27 13:52:04 -08:00
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
2022-01-27 13:52:04 -08:00
:::note
The CLI is able to take the `value` or the `name` of the sensor from the table above.
:::
```shell title="Set sensor type to DS18B20"
2022-06-25 00:39:41 -07:00
meshtastic --set environmental_measurement_plugin_sensor_type 2
2022-04-01 14:07:46 -07:00
````
```shell title="Set sensor type to DS18B20"
2022-06-25 00:39:41 -07:00
meshtastic --set environmental_measurement_plugin_sensor_type DS18B20
2022-01-27 13:52:04 -08:00
```
</TabItem>
<TabItem value="android">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
2022-01-27 13:52:04 -08:00
</TabItem>
<TabItem value="iOS">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
2022-01-27 13:52:04 -08:00
</TabItem>
<TabItem value="web">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
2022-01-27 13:52:04 -08:00
</TabItem>
</Tabs>
2022-06-25 00:39:41 -07:00
#### Set plugin update interval
<Tabs
groupId="settings"
defaultValue="cli"
values={[
{label: 'CLI', value: 'cli'},
{label: 'Android', value: 'android'},
{label: 'iOS', value: 'iOS'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="cli">
2022-06-25 00:39:41 -07:00
```shell title="Set plugin update interval to 120 seconds"
meshtastic --set environmental_measurement_plugin_update_interval 120
2022-04-01 14:07:46 -07:00
````
</TabItem>
<TabItem value="android">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="iOS">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
<TabItem value="web">
:::info
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
:::
</TabItem>
</Tabs>
## Details
### Hardware
The sensors can be wired differently, here's [one example](https://randomnerdtutorials.com/esp32-ds18b20-temperature-arduino-ide) for sensor DS18B20.
### Known Problems
2022-06-25 00:39:41 -07:00
- No default configuration values are currently set, so this must be done when enabling the plugin.