DigitalInfinity/ESP32-PaxCounter
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

formatting and more code examples

Browse Source
This commit is contained in:
Tim Huyeng 2022-11-21 23:05:57 +01:00
parent cec7e1916f
commit 67fabe67ed
7 changed files with 198 additions and 91 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
docs/additions.md
View File

@ -1,69 +0,0 @@
## Sensors and Peripherals
You can add up to 3 user defined sensors. Insert your sensor's payload scheme in [*sensor.cpp*](https://github.com/cyberman54/ESP32-Paxcounter/blob/master/src/sensor.cpp). Bosch BMP180 / BME280 / BME680 environment sensors are supported, to activate configure BME in board's hal file before build. Furthermore, SDS011, RTC DS3231, generic serial NMEA GPS, I2C LoPy GPS are supported, and to be configured in board's hal file. See [*generic.h*](https://github.com/cyberman54/ESP32-Paxcounter/blob/master/src/hal/generic.h) for all options and for proper configuration of BME280/BME680.
Output of user sensor data can be switched by user remote control command 0x14 sent to Port 2.
Output of sensor and peripheral data is internally switched by a bitmask register. Default mask can be tailored by editing *cfg.payloadmask* initialization value in [*configmanager.cpp*](https://github.com/cyberman54/ESP32-Paxcounter/blob/master/src/configmanager.cpp) following this scheme:
| Bit | Sensordata | Default |
| --- | ------------- | ------- |
| 0 | Paxcounter | on |
| 1 | unused | off |
| 2 | BME280/680 | on |
| 3 | GPS* | on |
| 4 | User sensor 1 | on |
| 5 | User sensor 2 | on |
| 6 | User sensor 3 | on |
| 7 | Batterylevel | off |
\*) GPS data can also be combined with paxcounter payload on port 1, *#define GPSPORT 1* in paxcounter.conf to enable
## Power saving mode
Paxcounter supports a battery friendly power saving mode. In this mode the device enters deep sleep, after all data is polled from all sensors and the dataset is completeley sent through all user configured channels (LORAWAN / SPI / MQTT / SD-Card). Set *#define SLEEPCYCLE* in paxcounter.conf to enable power saving mode and to specify the duration of a sleep cycle. Power consumption in deep sleep mode depends on your hardware, i.e. if on board peripherals can be switched off or set to a chip specific sleep mode either by MCU or by power management unit (PMU) as found on TTGO T-BEAM v1.0/V1.1. See [*power.cpp*](https://github.com/cyberman54/ESP32-Paxcounter/blob/master/src/power.cpp) for power management, and [*reset.cpp*](https://github.com/cyberman54/ESP32-Paxcounter/blob/master/src/reset.cpp) for sleep and wakeup logic.
## Time sync
Paxcounter can keep a time-of-day synced with external or on board time sources. Set *#define TIME_SYNC_INTERVAL* in paxcounter.conf to enable time sync. Supported external time sources are GPS, LORAWAN network time and LORAWAN application timeserver time. Supported on board time sources are the RTC of ESP32 and a DS3231 RTC chip, both are kept sycned as fallback time sources. Time accuracy depends on board's time base which generates the pulse per second. Supported are GPS PPS, SQW output of RTC, and internal ESP32 hardware timer. Time base is selected by #defines in the board's hal file, see example in [*generic.h*](https://github.com/cyberman54/ESP32-Paxcounter/blob/master/src/hal/generic.h). Bonus: If your LORAWAN network does not support network time, you can run a Node-Red timeserver application using the enclosed [**Timeserver code**](https://github.com/cyberman54/ESP32-Paxcounter/blob/master/src/Node-RED/Timeserver.json). Configure the MQTT nodes in Node-Red for the LORAWAN application used by your paxocunter device. Time can also be set without precision liability, by simple remote command, see section remote control.
## Wall clock controller
Paxcounter can be used to sync a wall clock which has a DCF77 or IF482 time telegram input. Set `#define HAS_IF482` or `#define HAS_DCF77` in board's hal file to setup clock controller. Use case of this function is to integrate paxcounter and clock. Accurary of the synthetic DCF77 signal depends on accuracy of on board's time base, see above.
## Mobile PaxCounter using <A HREF="https://opensensemap.org/">openSenseMap</A>
This describes how to set up a mobile PaxCounter:<br> Follow all steps so far for preparing the device, selecting the packed payload format. In `paxcounter.conf` set `PAYLOAD_OPENSENSEBOX` to `1`. Register a new sensebox on [https://opensensemap.org/](https://opensensemap.org). In the sensor configuration select "TheThingsNetwork" and set decoding profile to "LoRa serialization". Enter your TTN Application and Device ID. Setup decoding option using `[{"decoder":"latLng"},{"decoder":"uint16",sensor_id":"yoursensorid"}]`.
## SD-card
Data can be stored on SD-card if the board provides an SD card interface, either with SPI or MMC mode. To enable this feature, specify interface mode and hardware pins in board's hal file (src/hal/<board.h\>):
#define HAS_SDCARD 1 // SD-card interface, using SPI mode
OR
#define HAS_SDCARD 2 // SD-card interface, using MMC mode
// Pins for SPI interface
#define SDCARD_CS (13) // fill in the correct numbers for your board
#define SDCARD_MOSI (15)
#define SDCARD_MISO (2)
#define SDCARD_SCLK (14)
This is an example of a board with MMC SD-card interface: https://www.aliexpress.com/item/32915894264.html. For this board use file src/hal/ttgov21new.h and add the lines given above.
Another approach would be this tiny board: https://www.aliexpress.com/item/32424558182.html (needs 5V).
In this case you choose the correct file for your ESP32-board in the src/hal-directory and add the lines given above. Edit the pin numbers given in the example, according to your wiring.
Data is written on SD-card to a single file. After 3 write operations the data is flushed to the disk to minimize flash write cycles. Thus, up to the last 3 records of data will get lost when the PAXCOUNTER looses power during operation.
Format of the resulting file is CSV, thus easy import in LibreOffice, Excel, InfluxDB, etc. Each record contains timestamp (in ISO8601 format), paxcount (wifi and ble) and battery voltage (optional). Voltage is logged if the device has a battery voltage sensor (to be configured in board hal file).
File contents example:
```csv
timestamp,wifi,ble[,voltage]
2022-01-30T21:12:41Z,11,25[,4100]
2022-01-30T21:14:24Z,10,21[,4070]
2022-01-30T21:16:08Z,12,26[,4102]
2022-01-30T21:17:52Z,11,26[,4076]
```
If you want to change this, modify `src/sdcard.cpp` and `include/sdcard.h`.

3
docs/configuration/custom-sensors.md Normal file
View File

@ -0,0 +1,3 @@
# Custom sensors
!!! todo

146
docs/configuration/index.md Normal file
View File

@ -0,0 +1,146 @@
# Configuration
## Sensors and Peripherals
You can add up to 3 user defined sensors. Insert your sensor's payload scheme in [*sensor.cpp*](https://github.com/cyberman54/ESP32-Paxcounter/blob/master/src/sensor.cpp). More examples and a detailed description can be found in the [sensor documentation](custom-sensors.md).
### Supported Peripherals
* Bosch BMP180 / BME280 / BME680
* SDS011
* RTC DS3231
* generic serial NMEA GPS
* I2C Lopy GPS
For these peripherals no additional code is needed. To activate configure them in the board's hal file before building the code.
<!-- Bosch BMP180 / BME280 / BME680 environment sensors are supported without any additional code needed. To activate configure BME in board's hal file before build. -->
<!-- Furthermore, SDS011, RTC DS3231, generic serial NMEA GPS, I2C LoPy GPS are supported, and to be configured in board's hal file. -->
See [*generic.h*](https://github.com/cyberman54/ESP32-Paxcounter/blob/master/src/hal/generic.h) for all options and for proper configuration of BME280/BME680.
=== "BME/ BMP Configuration"
```c linenums="37" title="src/hal/generic.h"
--8<-- "src/hal/generic.h:37:49"
```
=== "SDS011 Configuration"
```c linenums="51" title="src/hal/generic.h"
--8<-- "src/hal/generic.h:51:56"
```
=== "Custom Sensors Configuration"
```c linenums="57" title="src/hal/generic.h"
--8<-- "src/hal/generic.h:57:60"
```
=== "Complete `generic.h`"
```c linenums="1" title="src/hal/generic.h"
--8<-- "src/hal/generic.h"
```
Output of user sensor data can be switched by user remote control command `0x14` sent to Port 2.
Output of sensor and peripheral data is internally switched by a bitmask register. Default mask can be tailored by editing *cfg.payloadmask* initialization value in [*configmanager.cpp*](https://github.com/cyberman54/ESP32-Paxcounter/blob/master/src/configmanager.cpp) following this scheme:
| Bit | Sensordata | Default |
| --- | ------------- | ------- |
| 0 | Paxcounter | on |
| 1 | unused | off |
| 2 | BME280/680 | on |
| 3 | GPS* | on |
| 4 | User sensor 1 | on |
| 5 | User sensor 2 | on |
| 6 | User sensor 3 | on |
| 7 | Batterylevel | off |
\*) GPS data can also be combined with paxcounter payload on port 1, `#define GPSPORT 1` in paxcounter.conf to enable
```c linenums="101" title="src/paxcounter_orig.conf"
--8<-- "src/paxcounter_orig.conf:101:101"
```
## Power saving mode
Paxcounter supports a battery friendly power saving mode. In this mode the device enters deep sleep, after all data is polled from all sensors and the dataset is completeley sent through all user configured channels (LORAWAN / SPI / MQTT / SD-Card). Set *#define SLEEPCYCLE* in paxcounter.conf to enable power saving mode and to specify the duration of a sleep cycle.
```c linenums="18" title="src/paxcounter_orig.conf"
--8<-- "src/paxcounter_orig.conf:18:18"
```
Power consumption in deep sleep mode depends on your hardware, i.e. if on board peripherals can be switched off or set to a chip specific sleep mode either by MCU or by power management unit (PMU) as found on TTGO T-BEAM v1.0/V1.1. See [*power.cpp*](https://github.com/cyberman54/ESP32-Paxcounter/blob/master/src/power.cpp) for power management, and [*reset.cpp*](https://github.com/cyberman54/ESP32-Paxcounter/blob/master/src/reset.cpp) for sleep and wakeup logic.
## Time sync
Paxcounter can keep a time-of-day synced with external or on board time sources. Set `#define TIME_SYNC_INTERVAL` in `paxcounter.conf` to enable time sync.
```c linenums="19" title="src/paxcounter_orig.conf"
--8<-- "src/paxcounter_orig.conf:87:87"
```
Supported external time sources are GPS, LORAWAN network time and LORAWAN application timeserver time. Supported on board time sources are the RTC of ESP32 and a DS3231 RTC chip, both are kept sycned as fallback time sources. Time accuracy depends on board's time base which generates the pulse per second. Supported are GPS PPS, SQW output of RTC, and internal ESP32 hardware timer. Time base is selected by #defines in the board's hal file, see example in [*generic.h*](https://github.com/cyberman54/ESP32-Paxcounter/blob/master/src/hal/generic.h).
```c linenums="87" title="src/hal/generic.h"
--8<-- "src/hal/generic.h:87:96"
```
!!! tip
Bonus: If your LORAWAN network does not support network time, you can run a Node-Red timeserver application using the enclosed [**Timeserver code**](https://github.com/cyberman54/ESP32-Paxcounter/blob/master/src/Node-RED/Timeserver.json). Configure the MQTT nodes in Node-Red for the LORAWAN application used by your paxocunter device. Time can also be set without precision liability, by simple remote command, see section remote control.
## Wall clock controller
Paxcounter can be used to sync a wall clock which has a DCF77 or IF482 time telegram input. Set `#define HAS_IF482` or `#define HAS_DCF77` in board's hal file to setup clock controller. Use case of this function is to integrate paxcounter and clock. Accurary of the synthetic DCF77 signal depends on accuracy of on board's time base, see above.
## Mobile PaxCounter using <A HREF="https://opensensemap.org/">openSenseMap</A>
This describes how to set up a mobile PaxCounter:<br> Follow all steps so far for preparing the device, selecting the packed payload format. In `paxcounter.conf` set `PAYLOAD_OPENSENSEBOX` to `1`.
```c linenums="59" title="src/paxcounter_orig.conf"
--8<-- "src/paxcounter_orig.conf:59:59"
```
Register a new sensebox on [https://opensensemap.org/](https://opensensemap.org). In the sensor configuration select "TheThingsNetwork" and set decoding profile to "LoRa serialization". Enter your TTN Application and Device ID. Setup decoding option using:
```json
[{"decoder":"latLng"},{"decoder":"uint16",sensor_id":"yoursensorid"}]
```
## SD-card
Data can be stored on SD-card if the board provides an SD card interface, either with SPI or MMC mode. To enable this feature, specify interface mode and hardware pins in board's hal file (`src/hal/<board.h\>`):
```c
#define HAS_SDCARD 1 // SD-card interface, using SPI mode
//OR
#define HAS_SDCARD 2 // SD-card interface, using MMC mode
// Pins for SPI interface
#define SDCARD_CS (13) // fill in the correct numbers for your board
#define SDCARD_MOSI (15)
#define SDCARD_MISO (2)
#define SDCARD_SCLK (14)
```
This is an example of a board with MMC SD-card interface: [https://www.aliexpress.com/item/32915894264.html](https://www.aliexpress.com/item/32915894264.html). For this board use file [`src/hal/ttgov21new.h`](https://github.com/cyberman54/ESP32-Paxcounter/blob/master/src/hal/ttgov21new.h) and add the lines given above.
Another approach would be this tiny board: [https://www.aliexpress.com/item/32424558182.html](https://www.aliexpress.com/item/32424558182.html) (needs 5V).
In this case you choose the correct file for your ESP32-board in the src/hal-directory and add the lines given above. Edit the pin numbers given in the example, according to your wiring.
Data is written on SD-card to a single file. After 3 write operations the data is flushed to the disk to minimize flash write cycles. Thus, up to the last 3 records of data will get lost when the Paxcounter looses power during operation.
Format of the resulting file is CSV, thus easy import in LibreOffice, Excel, InfluxDB, etc. Each record contains timestamp (in ISO8601 format), paxcount (wifi and ble) and battery voltage (optional). Voltage is logged if the device has a battery voltage sensor (to be configured in board hal file).
File contents example:
```csv
timestamp,wifi,ble[,voltage]
2022-01-30T21:12:41Z,11,25[,4100]
2022-01-30T21:14:24Z,10,21[,4070]
2022-01-30T21:16:08Z,12,26[,4102]
2022-01-30T21:17:52Z,11,26[,4076]
```
If you want to change this, modify `src/sdcard.cpp` and `include/sdcard.h`.

13
docs/hardware.md
View File

@ -61,4 +61,15 @@ Some 3D printable cases can be found (and, if wanted so, ordered) on Thingiverse
### Power consumption ### Power consumption
<b>Power consumption</b> was metered at around 450 - 1000mW, depending on board and user settings in `paxcounter.conf`. <b>Power consumption</b> was metered at around 450 - 1000mW, depending on board and user settings in `paxcounter.conf`.
By default, bluetooth sniffing not installed (`#define *BLECOUNTER* 0` in `paxcounter.conf`). If you enable bluetooth be aware that this goes on expense of wifi sniffing results, because then wifi and bt stack must share the 2,4 GHz RF ressources of ESP32. If you need to sniff wifi and bt in parallel and need best possible results, use two boards - one for wifi only and one for bt only - and add counted results.
By default, bluetooth sniffing not installed. If you enable bluetooth be aware that this goes on expense of wifi sniffing results, because then wifi and bt stack must share the 2,4 GHz RF ressources of ESP32. If you need to sniff wifi and bt in parallel and need best possible results, use two boards - one for wifi only and one for bt only - and add counted results.
<!-- TODO currently set to 1 here https://github.com/cyberman54/ESP32-Paxcounter/blob/master/src/paxcounter_orig.conf-->
=== "Deactivate BLE sniffing (Default)"
``` c linenums="29" title="paxcounter.conf"
#define *BLECOUNTER* 0
```
=== "Activate BLE sniffing"
``` c linenums="29" title="paxcounter.conf"
#define *BLECOUNTER* 1
```

10
docs/integrations.md
View File

@ -1,4 +1,6 @@
# Integration into "The Things Stack Community Edition" aka "The Things Stack V3" # Integration LoRaWAN
## "The Things Stack Community Edition" aka "The Things Stack V3"
To use the ESP32-Paxcounter in The Things Stack Community Edition you need an account to reach the console. Go to: To use the ESP32-Paxcounter in The Things Stack Community Edition you need an account to reach the console. Go to:
@ -12,6 +14,10 @@ To use the ESP32-Paxcounter in The Things Stack Community Edition you need an ac
The "Repository" payload decoder uses the packed format, explained below. If you want to use MyDevices from Cayenne you should use the Cayenne payload decoder instead. The "Repository" payload decoder uses the packed format, explained below. If you want to use MyDevices from Cayenne you should use the Cayenne payload decoder instead.
# TTN Mapper ## TTN Mapper
If you want your devices to be feeding the [TTN Mapper](https://ttnmapper.org/), just follow this manual: [https://docs.ttnmapper.org/integration/tts-integration-v3.html](https://docs.ttnmapper.org/integration/tts-integration-v3.html) - different than indicated in the manual you can leave the payload decoder to "Repository" for the ESP32-Paxcounter and you are fine. If you want your devices to be feeding the [TTN Mapper](https://ttnmapper.org/), just follow this manual: [https://docs.ttnmapper.org/integration/tts-integration-v3.html](https://docs.ttnmapper.org/integration/tts-integration-v3.html) - different than indicated in the manual you can leave the payload decoder to "Repository" for the ESP32-Paxcounter and you are fine.
## ChirpStack
!!! todo

42
docs/payloadformat.md
View File

@ -1,7 +1,7 @@
# Payload format # Payload format
You can select different payload formats in `paxcounter.conf`: You can select different payload formats in [`paxcounter.conf`](https://github.com/cyberman54/ESP32-Paxcounter/blob/master/src/paxcounter_orig.conf):
- ***Plain*** uses big endian format and generates json fields, e.g. useful for TTN console - ***Plain*** uses big endian format and generates json fields, e.g. useful for TTN console
@ -9,6 +9,12 @@ You can select different payload formats in `paxcounter.conf`:
- [***CayenneLPP***](https://mydevices.com/cayenne/docs/lora/#lora-cayenne-low-power-payload-reference-implementation) generates MyDevices Cayenne readable fields - [***CayenneLPP***](https://mydevices.com/cayenne/docs/lora/#lora-cayenne-low-power-payload-reference-implementation) generates MyDevices Cayenne readable fields
```c linenums="20" title="src/paxcounter_orig.conf"
--8<-- "src/paxcounter_orig.conf:20:20"
```
!!! danger "Decrepated information from the things network v2" !!! danger "Decrepated information from the things network v2"
If you're using [TheThingsNetwork](https://www.thethingsnetwork.org/) (TTN) you may want to use a payload converter. Go to TTN Console - Application - Payload Formats and paste the code example below in tabs Decoder and Converter. This way your MQTT application can parse the fields `pax`, `ble` and `wifi`. If you're using [TheThingsNetwork](https://www.thethingsnetwork.org/) (TTN) you may want to use a payload converter. Go to TTN Console - Application - Payload Formats and paste the code example below in tabs Decoder and Converter. This way your MQTT application can parse the fields `pax`, `ble` and `wifi`.
@ -41,22 +47,22 @@ Hereafter described is the default *plain* format, which uses MSB bit numbering.
**Port #3:** Device configuration query result **Port #3:** Device configuration query result
byte 1: Lora DR (0..15, see rcommand 0x05) [default 5] byte 1: Lora DR (0..15, see rcommand 0x05) [default 5]
byte 2: Lora TXpower (2..15) [default 15] byte 2: Lora TXpower (2..15) [default 15]
byte 3: Lora ADR (1=on, 0=off) [default 1] byte 3: Lora ADR (1=on, 0=off) [default 1]
byte 4: Screensaver status (1=on, 0=off) [default 0] byte 4: Screensaver status (1=on, 0=off) [default 0]
byte 5: Display status (1=on, 0=off) [default 0] byte 5: Display status (1=on, 0=off) [default 0]
byte 6: Counter mode (0=cyclic unconfirmed, 1=cumulative, 2=cyclic confirmed) [default 0] byte 6: Counter mode (0=cyclic unconfirmed, 1=cumulative, 2=cyclic confirmed) [default 0]
bytes 7-8: RSSI limiter threshold value (negative, MSB) [default 0] bytes 7-8: RSSI limiter threshold value (negative, MSB) [default 0]
byte 9: Scan and send cycle in seconds/2 (0..255) [default 120] byte 9: Scan and send cycle in seconds/2 (0..255) [default 120]
byte 10: Wifi channel hopping interval in seconds/100 (0..255), 0 means no hopping [default 50] byte 10: Wifi channel hopping interval in seconds/100 (0..255), 0 means no hopping [default 50]
byte 11: Bluetooth channel switch interval in seconds/100 (0..255) [default 10] byte 11: Bluetooth channel switch interval in seconds/100 (0..255) [default 10]
byte 12: Bluetooth scanner status (1=on, 0=0ff) [default 1] byte 12: Bluetooth scanner status (1=on, 0=0ff) [default 1]
byte 13: Wifi antenna switch (0=internal, 1=external) [default 0] byte 13: Wifi antenna switch (0=internal, 1=external) [default 0]
byte 14: 0 (reserved) byte 14: 0 (reserved)
byte 15: RGB LED luminosity (0..100 %) [default 30] byte 15: RGB LED luminosity (0..100 %) [default 30]
byte 16: Payloadmask (Bitmask, 0..255, see rcommand 0x14) byte 16: Payloadmask (Bitmask, 0..255, see rcommand 0x14)
byte 17: 0 (reserved) byte 17: 0 (reserved)
bytes 18-28: Software version (ASCII format, terminating with zero) bytes 18-28: Software version (ASCII format, terminating with zero)
@ -70,7 +76,7 @@ Hereafter described is the default *plain* format, which uses MSB bit numbering.
**Port #5:** Button pressed alarm **Port #5:** Button pressed alarm
byte 1: static value 0x01 byte 1: static value 0x01
**Port #6:** (unused) **Port #6:** (unused)

6
mkdocs.yml
View File

@ -5,6 +5,8 @@ theme:
features: features:
- navigation.instant - navigation.instant
- navigation.tracking - navigation.tracking
- navigation.indexes
- content.code.annotate
palette: palette:
# Palette toggle for light mode # Palette toggle for light mode
- media: "(prefers-color-scheme: light)" - media: "(prefers-color-scheme: light)"
@ -26,7 +28,9 @@ nav:
- Getting Started: getting-started.md - Getting Started: getting-started.md
- Display & LED: display-led.md - Display & LED: display-led.md
- Legal note: legalnote.md - Legal note: legalnote.md
- Additions: additions.md - Configuration:
- configuration/index.md
- Custom Sensors: modifications/custom-sensors.md
- Integrations: integrations.md - Integrations: integrations.md
- Payload Format: payloadformat.md - Payload Format: payloadformat.md
- Remote control: remotecontrol.md - Remote control: remotecontrol.md