Skip to main content

💻 Firmware

Environment

Dev Environment Setup

  1. Clone this repository;
  2. Open Particle Workbench;
  3. Run the Particle: Import Project command, follow the prompts, and wait for the project to load;
  4. Run the Particle: Configure Workspace for Device command and select a compatible Device OS version and the bsom platform when prompted (docs);
  5. Connect your device;
  6. Compile & Flash!

Quick overview of classes and files

  • cityscanner_config.h main config file, needs to be updated before flashing;
  • main.h the program startpoint, should not be modified;
  • cityscanner class handles operation modes (more below);
  • CitySense class manages data acquisition for environemental sensors (air quality, etc);
  • CityVitals class acquires telemetry data (battery status, solar energy production, etc);
  • CityStore class manages storing data on the SDcard, dumping data over TCP and over Particle Publish methods;
  • MotionService class used to send the device to sleep when the vehicle is not moving;
  • LocationService class provides gps data to other classes (e.g. CityStore).

Operation modes

  • IDLE sensors off, provides only telemetry data;
  • REALTIME logs data onto the SD card and send it in real time (via Particle publish);
  • LOGGING buffer data onto the SD card and send multiple records upon request (via TCP);
  • PWRSAVE like LOGGING but keeping the cellular modem OFF.

Payload

deviceID, timestamp, latitude, longitude, PM1.0, PM 2.5, PM4, PM10, numPM0.5, numPM1, numPM2.5, numPM4, numPM10, PM size, temperature, humidity, gas_op1_w, gas_op1_r, gas_op2_w, gas_op2_r, noise, Thermal

Vitals

deviceID, timestamp, latitude, longitude, voltage_batt, current_batt, isCharging, isCharginS, isCharged, temp_int, hum_int, voltage_solar, current_solar, cell_strenght

Command line interface

The CLI is available via REST, Particle.io Console and Slack. Each command might have 0-3 parameters. Some command return via Particle events or serial.

tip

Commands are comma-separated.

CommandParam.#1Param.#2Description
batteryReturns battery state_of_charge, temperature, voltage, voltage_alt, current, isCharging
solarReturns solar panel voltage, current
stopStops the device (light sleep) for 12hours or until it woken up by a motion even
hibernate[duration]seconds, minutes or hoursHibernates the device (heavy sleep)
rebootResets the device to default
locationReturns the latest known GPS coordinates
devicecheckReturns the device ID and last payload, useful for multiple devices
lastpayloadReturns the last payload (See payload schema above)
lastvitalsReturns the last vitals (See vitals schema above)
sdfilesReturns n. of files buffered in the SD card
sddumpallDumps all files queued on the SD to mongoDB via TCP
sddump[files_number]Dumps the number of files passed as parameter to mongoDB via TCP
sdformatFormats SD card DO NOT USE
cellularOFFTurns off the cellular modem untill the device is manually powercycled
autosleeponDevice goes to sleep after x minutes of no motion
autosleepoff
heat-coolonTurns on the heater or the fan
heat-cooloff