Key features
Our PyonAir software allows the device to:
Show device status using the RGB LED
Additional detail is given below.
Read temperature & humidity data
If the temperature & humidity sensor is enabled by the user, a class object of the chosen sensor is initialised. (Default to SHT35.) A periodic interrupt is triggered from the main thread, which reads the current temperature and humidity, and logs it to the terminal and to a file in the 'Current' directory. The period is set by the user, and it is recommended to be more than 3 minutes to save processing power, and mitigate heating effects.
Missed readings are logged, and a red LED blink is scheduled to let the user know something went wrong. If the device keeps blinking, the sensors are worth checking.
Read particulate matter data
Start a thread for each enabled PM sensor, which reads from the sensor and logs the reading to the terminal and to a file in the 'Current' directory. The read is triggered by a periodic interrupt every second. Upon initialising the thread, there is a warm-up period specified by the user, during which no readings are logged to make sure the sensors have time to calibrate.
Missed readings are logged, and a red LED blink is scheduled to let the user know something went wrong. If the device keeps blinking the sensors are worth checking.
If none of the PM sensors are enabled, a transistor makes sure that nothing gets powered by the PM1 and PM2 Grove sockets.
Plantower PMS3005
More info coming soon! 🐱👤
Sensirion SPS30
More info coming soon! 🌳
Calculate averages
Calculating averages happens at the end of each interval. It takes the raw data files of enabled sensors (PM1, PM2, TEMP) from the 'Current' directory, and moves it to the 'Processing' directory. It then takes the average of requested columns and constructs a LoRa message with a given format based on the type of sensors that are enabled. The LoRa message is pushed to the LoRa Ring Buffer, and a copy is appended to a file separated by months in the 'Averages' folder in the 'Archive' directory. The raw data is then moved from the 'Processing' directory to the 'Archive'.
Time acquisition
Tries to read current UTC time from the external RTC module and updates the RTC on the pycom board upon success.
If the RTC module is not connected, or it is not configured, tries to get time from the GPS module, which updates time on the RTC module (if connected) and the RTC on the pycom board if succeeds.
If none of these succeed, an exception is raised. At this point the user is given a table of possible issues and solutions (by the logger) on how to set UTC to continue execution.
Location acquisition
Upon a GPS event a transistor is turned on to power the GPS module, and a serial bus is initialised to communicate with the sensor. Since the maximum number of UART buses are 3 on the pycom board, the terminal output is disabled while the GPS operates. The GPS continuously receives and parses sentences from the satellites until the quality reaches the desired HDOP based on the percentage of time elapsed until the given timeout. When latitude, longitude and altitude are updated, a LoRa message is constructed with the given format, and pushed to the LoRa Ring Buffer. The message is also logged to 'Archive'.
The device also recognises if the GPS is enabled in configurations, but the module itself is not connected. In that case the thread timeouts in 10 seconds instead of the user set timeout.
User button
Initialises an interrupt triggered by the button labelled as 'config' on the expansion board.
A press no longer than a second triggers a soft reset, while a press held for 3 seconds enters configuration mode.
Should the soft reset fail, the user will have to press the reset button on the pycom board.
Configuration
Upon pressing the config button for longer than 3 seconds, blue light flashes, and configuration mode is entered. During configuration mode the device turns into an access point with the name "NewPyonAir", and password "newpyonair", or whatever the device name and password were set previously. The user has to connect to the device on WiFi and navigate to http://192.168.4.10 in their browser. Once the user has connected, and opened the configurations page, green light flashes on the device.
To configure the device, all fields have to be filled in, and the 'Save' button has to be pressed, when the device saves the new configuration to the SD card, sets time on the RTC module, reboots and continues to run according to the new configurations. Note, that once configuration mode is entered, the device will reboot, even if the process does not succeed, when red light flashes for 3 seconds before the device proceeds to reboot.
Queue and scheduler
Event scheduler
The Event Scheduler is responsible for triggering periodic events, such as calculating sensor averages, getting position over the GPS, and sending data over LoRaWAN. Upon initialisation it calculates when the first event should occur, so the interval is divisible by the number of seconds of the day that will have passed by the first event. The first event then starts a periodic interrupt with the given interval to set up the event queue.
LoRa airtime
If LoRaWAN is enabled by the user, the device attempts to connect to The Things Network using OTAA.
In the LoRa send method, the most recent message is popped from the stack and sent over LoRa to the given port with the required format.
The stack (LoRa Ring Buffer) stores unsent messages, to make sure everything will be sent, even if there is no connection for a period of time. Messages older than a month are automatically deleted, and at full capacity it is guaranteed that 22 days worth of backed-up data is dealt with provided that a stable connection returns.
The event scheduler is also responsible to limit the airtime over LoRa. Currently the Fair Access Policy on TTN limits the airtime to 30s per day. The event scheduler keeps track of how many messages it has sent on the day (even if the device was rebooted), and schedules 1-4 randomly timed messages during an interval. The number of messages depends on the size of the Lora Stack, the number of messages sent on the day, and also on the length of the interval. Real time transmission is guaranteed if the interval is less than 4 minutes if the stack is empty, and less than 15 minutes if the stack is full. The absolute minimum interval is 1 minute.
Check for updates
There are two types of Version Numbers that are set by the developer here.
The first one is the format version, which is used to tell the decoder at the back-end what format scheme the device uses to encode the LoRa messages.
The second one is the code version, which is the git tag corresponding to current commit. The code version is important to compare differences upon the event of an OTA update.
Device updates are triggered by a LoRa message sent to the PyonAir. If there is an update scheduled, the current code version is compared to the one on a server, and the software is updated over WiFi, if an update is available. The device then proceeds to reboot.
Logging
The Status Logger is the main logger used to log all exceptions and information to the SD card (status_logger.txt), and to the terminal as well.
Levels: Critical, Error, Warning, Info and Debug
LED indicator
The RGB LED is used extensively to indicate the current status of the device, and is extremely useful when dealing with errors. (See exception handling in the main.) The user should always go through the initialisation phase upon boot paying close attention to the LED. If there is a periodic red blink or no green heartbeat every 5 seconds, something has probably gone wrong, and requires immediate attention.
Pycom's built-in heartbeat has to be turned off and back on again every time the LEDs are used, and it often causes an error, which forces the device to reboot itself. Therefore, the heartbeat is simulated using a green LED blink every 5 seconds triggered by a periodic timer interrupt from the main instead of the built-in pycom method.
Last updated