diff --git a/docs/additions.md b/docs/additions.md index 08208b9e..045df9c7 100644 --- a/docs/additions.md +++ b/docs/additions.md @@ -17,27 +17,27 @@ Output of sensor and peripheral data is internally switched by a bitmask registe | 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 +\*) 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* for power management, and *reset.cpp* for sleep and wakeup logic. +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. +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. +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 openSenseMap -This describes how to set up a mobile PaxCounter:
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/. 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"}]` +This describes how to set up a mobile PaxCounter:
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/): +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/): #define HAS_SDCARD 1 // SD-card interface, using SPI mode OR @@ -56,7 +56,7 @@ In this case you choose the correct file for your ESP32-board in the src/hal-dir 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, Influx, 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). +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 @@ -66,4 +66,4 @@ File contents example: 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. \ No newline at end of file +If you want to change this, modify `src/sdcard.cpp` and `include/sdcard.h`. \ No newline at end of file diff --git a/docs/display-led.md b/docs/display-led.md new file mode 100644 index 00000000..3f0f5631 --- /dev/null +++ b/docs/display-led.md @@ -0,0 +1,32 @@ +# Display + +![Display Image](img/Paxcounter-Screen.png) + +If you're using a device with OLED display, or if you add such one to the I2C bus, the device shows live data on the display. You can flip display pages showing + +- recent count of pax +- histogram +- GPS data +- BME sensor data +- time of day +- blank page + +by pressing the button of the device. + +# LED blink pattern + +**Mono color LED:** + +- Single Flash (50ms): seen a new Wifi or BLE device +- Quick blink (20ms on each 1/5 second): joining LoRaWAN network in progress or pending +- Small blink (10ms on each 1/2 second): LoRaWAN data transmit in progress or pending +- Long blink (200ms on each 2 seconds): LoRaWAN stack error + +**RGB LED:** + +- Green: seen a new Wifi device +- Magenta: seen a new BLE device +- Yellow: joining LoRaWAN network in progress or pending +- Pink: LORAWAN MAC transmit in progress +- Blue: LoRaWAN data transmit in progress or pending +- Red: LoRaWAN stack errors \ No newline at end of file diff --git a/docs/display.md b/docs/display.md deleted file mode 100644 index b564bdf3..00000000 --- a/docs/display.md +++ /dev/null @@ -1,14 +0,0 @@ -# Display - -![Display Image](img/Paxcounter-Screen.png) - -If you're using a device with OLED display, or if you add such one to the I2C bus, the device shows live data on the display. You can flip display pages showing - -- recent count of pax -- histogram -- GPS data -- BME sensor data -- time of day -- blank page - -by pressing the button of the device. \ No newline at end of file diff --git a/docs/installation.md b/docs/getting-started.md similarity index 92% rename from docs/installation.md rename to docs/getting-started.md index 2741bb4f..b0801e2e 100644 --- a/docs/installation.md +++ b/docs/getting-started.md @@ -2,12 +2,16 @@ ## Install Platformio -Install PlatformIO IDE for embedded development to make this project. Platformio integrates with your favorite IDE, choose eg. Visual Studio, Atom, Eclipse etc. +Install PlatformIO IDE for embedded development to build this project. Platformio integrates with your favorite IDE, choose e.g. Visual Studio Code, Atom, Eclipse etc. Compile time configuration is spread across several files. Before compiling the code, edit or create the following files: ## platformio.ini -Edit `platformio_orig.ini` (for ESP32 CPU based boards) *or* `platformio_orig_s3.ini` (for ESP32-S3 CPU based boards) and select desired board in section **board**. To add a new board, create an appropriate hardware abstraction layer file in hal subdirectory, and add a pointer to this file in section **board**. Copy or rename to `platformio.ini` in the root directory of the project. Now start Platformio. Note: Platformio is looking for `platformio.ini` in the root directory and won't start if it does not find this file! +Edit `platformio_orig.ini` (for ESP32 CPU based boards) *or* `platformio_orig_s3.ini` (for ESP32-S3 CPU based boards) and select desired board in section **board**. To add a new board, create an appropriate hardware abstraction layer file in hal subdirectory, and add a pointer to this file in section **board**. Copy or rename to `platformio.ini` in the root directory of the project. Now start Platformio. + +!!! info + + Note: Platformio is looking for `platformio.ini` in the root directory and won't start if it does not find this file! ## paxcounter.conf Edit `src/paxcounter_orig.conf` and tailor settings in this file according to your needs and use case. Please take care of the duty cycle regulations of the LoRaWAN network you're going to use. Copy or rename to `src/paxcounter.conf`. @@ -24,7 +28,7 @@ To configure OTAA, leave `#define LORA_ABP` deactivated (commented). To use ABP, The file `src/loraconf_sample.h` contains more information about the values to provide. ## src/ota.conf -Create file `src/ota.conf` using the template [src/ota.sample.conf](https://github.com/cyberman54/ESP32-Paxcounter/blob/master/src/ota.sample.conf) and enter your WIFI network&key. These settings are used for downloading updates via WiFi, either from a remote https server, or locally via WebUI. If you want to use a remote server, you need a PAX.express repository. Enter your PAX.express credentials in ota.conf. If you don't need wireless firmware updates just rename ota.sample.conf to ota.conf. +Create file `src/ota.conf` using the template [src/ota_sample.conf](https://github.com/cyberman54/ESP32-Paxcounter/blob/master/src/ota_sample.conf) and enter your WIFI network&key. These settings are used for downloading updates via WiFi, either from a remote https server, or locally via WebUI. If you want to use a remote server, you need a PAX.express repository. Enter your PAX.express credentials in ota.conf. If you don't need wireless firmware updates just rename ota.sample.conf to ota.conf. # Building diff --git a/docs/integrations.md b/docs/integrations.md index faf8c743..191cfdb6 100644 --- a/docs/integrations.md +++ b/docs/integrations.md @@ -1,6 +1,7 @@ # Integration into "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: + - [The Things Stack Community Edition Console](https://console.cloud.thethings.network/) - choose your region and go to applications - create an application by clicking "**+ Add application**" and give it a id, name, etc. @@ -13,4 +14,4 @@ The "Repository" payload decoder uses the packed format, explained below. If you # 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 - 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. diff --git a/docs/led.md b/docs/led.md index 09f49c0f..e69de29b 100644 --- a/docs/led.md +++ b/docs/led.md @@ -1,17 +0,0 @@ -# LED blink pattern - -**Mono color LED:** - -- Single Flash (50ms): seen a new Wifi or BLE device -- Quick blink (20ms on each 1/5 second): joining LoRaWAN network in progress or pending -- Small blink (10ms on each 1/2 second): LoRaWAN data transmit in progress or pending -- Long blink (200ms on each 2 seconds): LoRaWAN stack error - -**RGB LED:** - -- Green: seen a new Wifi device -- Magenta: seen a new BLE device -- Yellow: joining LoRaWAN network in progress or pending -- Pink: LORAWAN MAC transmit in progress -- Blue: LoRaWAN data transmit in progress or pending -- Red: LoRaWAN stack errors \ No newline at end of file diff --git a/docs/legalnote.md b/docs/legalnote.md index 27722abf..790551db 100644 --- a/docs/legalnote.md +++ b/docs/legalnote.md @@ -2,15 +2,18 @@ **Depending on your country's laws it may be illegal to sniff wireless networks for MAC addresses. Please check and respect your country's laws before using this code!** -(e.g. US citizens may want to check [Section 18 U.S. Code § 2511](https://www.law.cornell.edu/uscode/text/18/2511) and [discussion](https://github.com/schollz/howmanypeoplearearound/issues/4) on this) +- (e.g. US citizens may want to check [Section 18 U.S. Code § 2511](https://www.law.cornell.edu/uscode/text/18/2511) and [discussion](https://github.com/schollz/howmanypeoplearearound/issues/4) on this) -(e.g. UK citizens may want to check [Data Protection Act 1998](https://ico.org.uk/media/1560691/wi-fi-location-analytics-guidance.pdf) and [GDPR 2018](https://ico.org.uk/for-organisations/guide-to-the-general-data-protection-regulation-gdpr/key-definitions/)) +- (e.g. UK citizens may want to check [Data Protection Act 1998](https://ico.org.uk/media/1560691/wi-fi-location-analytics-guidance.pdf) and [GDPR 2018](https://ico.org.uk/for-organisations/guide-to-the-general-data-protection-regulation-gdpr/key-definitions/)) -(e.g. Citizens in the the Netherlands and EU may want to read [this article](https://www.ivir.nl/publicaties/download/PrivacyInformatie_2016_6.pdf) and [this article](https://autoriteitpersoonsgegevens.nl/nl/nieuws/europese-privacytoezichthouders-publiceren-opinie-eprivacyverordening)) and [this decision](https://edpb.europa.eu/news/national-news/2021/dutch-dpa-fines-municipality-wi-fi-tracking_en) +- (e.g. Citizens in the the Netherlands and EU may want to read [this article](https://www.ivir.nl/publicaties/download/PrivacyInformatie_2016_6.pdf) and [this article](https://autoriteitpersoonsgegevens.nl/nl/nieuws/europese-privacytoezichthouders-publiceren-opinie-eprivacyverordening) and [this decision](https://edpb.europa.eu/news/national-news/2021/dutch-dpa-fines-municipality-wi-fi-tracking_en)) -(e.g. Citizens in Germany may want to read [this article of Wissenschaftliche Dienste des Deutschen Bundestages](https://www.bundestag.de/resource/blob/538890/3dfae197d2c930693aa16d1619204f58/WD-3-206-17-pdf-data.pdf) +- (e.g. Citizens in Germany may want to read [this article of Wissenschaftliche Dienste des Deutschen Bundestages](https://www.bundestag.de/resource/blob/538890/3dfae197d2c930693aa16d1619204f58/WD-3-206-17-pdf-data.pdf)) -Note: If you use this software you do this at your own risk. That means that you alone - not the authors of this software - are responsible for the legal compliance of an application using this or build from this software and/or usage of a device created using this software. You should take special care and get prior legal advice if you plan metering passengers in public areas and/or publish data drawn from doing so. + +!!! info + + Note: If you use this software you do this at your own risk. That means that you alone - not the authors of this software - are responsible for the legal compliance of an application using this or build from this software and/or usage of a device created using this software. You should take special care and get prior legal advice if you plan metering passengers in public areas and/or publish data drawn from doing so. # Privacy disclosure diff --git a/docs/license-credits.md b/docs/license-credits.md index 8b75fbe1..bfb261a5 100644 --- a/docs/license-credits.md +++ b/docs/license-credits.md @@ -23,6 +23,7 @@ see file + +![Remote Control](img/paxcounter_downlink_example.png) 0x01 set scan RSSI limit diff --git a/mkdocs.yml b/mkdocs.yml index 26e29979..153d5871 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -3,18 +3,33 @@ theme: name: material features: - navigation.tracking + palette: + # Palette toggle for light mode + - media: "(prefers-color-scheme: light)" + scheme: default + toggle: + icon: material/brightness-7 + name: Switch to dark mode + + # Palette toggle for dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + toggle: + icon: material/brightness-4 + name: Switch to system preference + primary: indigo nav: - Intro: index.md - Hardware: hardware.md - - Getting Started: installation.md - - Display: display.md - - LED: led.md - - legalnote: legalnote.md + - Getting Started: getting-started.md + - Display & LED: display-led.md + - Legalnote: legalnote.md - Additions: additions.md - Integrations: integrations.md - Payload Format: payloadformat.md - Remote control: remotecontrol.md - Licence and Credits: license-credits.md + - Releases: releases.md markdown_extensions: - pymdownx.highlight: @@ -24,5 +39,8 @@ markdown_extensions: - pymdownx.superfences - attr_list - md_in_html + - admonition + - pymdownx.details + - pymdownx.superfences repo_url: https://github.com/cyberman54/ESP32-Paxcounter \ No newline at end of file