bcmeter.org - User contributions [en]

Introduction

2026-06-08T19:17:02Z

Bcmwiki: Consistency: 'open design/PCB' -> 'source-available' per licensing decision

== Introduction ==

The '''bcMeter''' is a source-available optical absorption photometer designed to measure Black Carbon (BC) aerosols — commonly known as soot — in real-time. The design is freely available for private, educational and research use (CC BY-NC 4.0); assembled instruments are offered on request. Whether you are monitoring ambient air quality in your neighborhood or measuring direct emissions from wood stoves, this device provides scientific-grade data at a fraction of the cost of reference instruments.

The device operates "headless" — it has no built-in screen. Instead, it hosts its own website that you can access from any smartphone or computer connected to the same network.

The software is source-available — freely available for private, educational and research use (CC BY-NC 4.0): [https://github.com/dahljo/bcmeter-pi github.com/dahljo/bcmeter-pi]

=== Device Types ===

* '''bcMeter (DIY)''' — The source-available, self-build version. Runs on a Raspberry Pi using the source-available PCB design, freely available for private, educational and research use (CC BY-NC 4.0). Build your own from the source-available design files and the Wiki (nothing is sold).
* '''bcMeter Kit''' — Assembled-instrument PCB plus components for self-assembly and 3D printing. Available on request.
* '''bcMeter Complete''' — Fully assembled, ready-to-use instrument on a compact platform that starts in seconds and updates over the air, with no microSD card or Linux system to maintain. Available on request.
* '''eBcMeter''' — Emission measurement instrument for direct source sampling from wood-burning stoves and similar combustion sources. Uses microgram (µg) units instead of nanogram (ng). Available on request.

=== How Does It Work? ===

[[File:Working principle of a bcMeter.png|300px|right]]

# Polluted air is drawn through filter paper by a pump
# The filter paper absorbs black carbon (BC) particles
# An LED shining at 880 nm passes through the filter; a sensor measures the attenuation (reduction in light intensity)
# A separate reference channel monitors the same LED through a clean portion of the filter, compensating for environmental changes
# The attenuation is converted to BC concentration (ng/m³) using Beer-Lambert law
# Data is saved as CSV and displayed in real-time on the web interface

'''Multi-wavelength (in development):''' Additional 520 nm and 370 nm channels for source apportionment via the Ångström Exponent (AAE) are in development and '''not available in shipped hardware'''. Current devices measure at 880 nm only.

=== Sensors & Capabilities ===

==== Core ====

{| class="wikitable"
! Measurement !! Sensor / Method !! Notes
|-
| Black Carbon (BC) || Optical absorption at 880 nm || Primary measurement
|-
| Temperature / Humidity || SHT4x ||
|-
| Airflow || Omron D6F differential pressure || Pump flow rate
|}

==== Optional Hardware ====

{| class="wikitable"
! Measurement !! Sensor / Method !! Notes
|-
| Temperature / Humidity / Pressure || BME280 || Barometric altitude
|-
| PM2.5 / PM10 || Sensirion SPS30 || Particulate matter
|-
| GPS || AT6668 UART || Position, altitude, speed
|-
| 4G Connectivity || SIM7080G LTE-M modem || Remote data upload
|}

Bill of material

2026-06-08T19:10:05Z

Bcmwiki: Fix GitHub org: bcmeter/bcmeter -> dahljo/bcmeter (legacy V1 Pi repo)

{{Note|1='''bcMeter (DIY)''' — This page documents the bill of materials for the source-available bcMeter (DIY) — the Raspberry-Pi-based design, freely available for private, educational and research use (CC BY-NC 4.0). The assembled bcMeter instruments use a different PCB design.}}

== Overview of Parts (bcMeter DIY) ==

[[File:bcMeter_parts.jpg|thumb|none|800px]]

== Mandatory Components ==

# '''bcMeter Pi Hat''' — Order prepopulated (~95 EUR) or build your own from PCB + components (~5 EUR per PCB for 10+ on JLCPCB or similar)
# '''Raspberry Pi 3A or Zero 2 W''' (~35 EUR)
# '''MicroSD Card''' (~10 EUR)
# '''Power Supply 5.25V/2A''' (~15 EUR)
# '''Air Pump''' (~10–200 EUR depending on type)

''Prefer not to source parts? bcMeter Kit/Complete available on request — contact jd@bcmeter.org.''

== 3D Printed Case ==

STL files for 3D Printing (SLA or FDM): [https://github.com/dahljo/bcmeter/tree/main/stl GitHub repository] — printing material ~10 EUR.

Use black filament/resin. FDM is prone to leakage if not properly configured. If possible, mix resin with flex resin.

== Filter Paper ==

AE33 filter paper is standard for bcMeter. Any filter paper with a known scattering factor can be used. See [[Best practices#Supported Filter Papers|Supported Filter Papers]] for correction factors.

Send a sample of your filter paper to jd@bcmeter.org for calibration.

== Additional Material (~75 EUR) ==

{| class="wikitable"
! Description !! Quantity !! Approx. Price
|-
| 22 AWG Wire || 1 || $10
|-
| Hot Glue || 1 || $7
|-
| Rubber Band (SHORE A) for sealing || 1 || $13
|-
| Silicone Hose (5mm ID) || 1 || $5
|-
| M3 Screws || 1 set || $7
|-
| M3 Threaded Inserts || 1 set || $7
|-
| MicroSD Card 16GB || 1 || $8
|}

== Key PCB Components ==

{| class="wikitable"
! Component !! Description !! Approx. Price
|-
| '''U1''' MCP3428 || 4-Channel ADC || €6
|-
| '''D1/D2''' IRL81A || IR LEDs (880nm) || €2
|-
| '''J1''' Omron D6F || Airflow Sensor || €50
|-
| '''U2''' LM1117 || Voltage Regulator || €1
|-
| '''U3''' SHT4x || Humidity/Temp Sensor || €4
|-
| '''Pump''' D15S PWM || Membrane Pump || €95
|-
| Capacitors, resistors, connectors || Various || ~€20
|}

Full BOM with exact product numbers available at [https://github.com/dahljo/bcmeter GitHub].

== PCB / Gerber Files ==

Gerber files for PCB fabrication: [https://github.com/dahljo/bcmeter/tree/main/gerbers GitHub]

Two PCB variants exist:
* '''SMD PCB''' — For 5V and smaller pumps. More compact, recommended.
* '''THT PCB''' — For 12V and larger pumps. Easier to assemble but less accurate.

== Assembled instruments (Kit/Complete/eBcMeter) ==

The assembled bcMeter instruments use a different hardware design:

* '''ADS1220''' 24-bit ADC (replaces MCP3428)
* '''Integrated microcontroller''' (instead of the Raspberry Pi used in the DIY build)
* '''Internal flash storage''' (replaces microSD)
* '''Optional:''' SIM7080G LTE-M modem, AT6668 GPS, SPS30 PM sensor

For current device information, see [[Introduction]].

Maintenance

2026-06-08T18:59:35Z

Bcmwiki: Restructure: platform separation (ESP32 commercial prioritised, Raspberry Pi DIY in own section); verified against firmware/Pi source; complete serial command list

== Maintenance Procedures ==

Open maintenance functions with the '''Maintenance''' button in the navigation bar. The modal has cards for device management, system status, time synchronization, and geolocation.

=== Filter Change Procedure ===

'''The filter is not identical on both sides.'''

* Identify the side with markings (black line, dot, or circles).
* The '''marked side must face UP''' (towards the LEDs/light source in the upper optical chamber).

'''Warning:''' Incorrect orientation (marked side down) results in ~30% measurement error.

'''Procedure:'''

# Stop any running session.
# Unscrew the top cap of the optical chamber.
# Remove the saturated filter.
# Insert a new filter with '''markings facing up'''.
# Screw the cap back on (hand-tight).
# '''Check hose''' (if used): check that the air hose is still connected to the inlet port.
# '''Run [[Maintenance#Calibration|Calibration]] (required).'''

=== Calibration ===

Filters vary slightly in optical density. Calibration balances the sensor signal against the reference signal for the specific filter currently installed.

# Go to '''Maintenance''' > '''Calibrate Device'''.
# Check that a '''new and clean filter''' is installed.
# Click "Yes."
# A progress bar appears. The device adjusts LED intensity per channel to find stable reference and sensor readings.
# Wait for "Calibration Successful" before starting a new log.

'''Technical detail:''' Calibration determines the per-channel correction factor K = Ref_avg / Sen_avg and stores it with the LED duty cycle values. Calibration typically takes 30–60 seconds.

=== Data Management ===

Click '''Log Files''' to open the data manager. The modal lists all stored sessions:

{| class="wikitable"
! Column !! Description
|-
| '''Log''' || Session name or filename (e.g., <code>26-03-12_212600.csv</code>). "Current Session" shows the active log.
|-
| '''Size''' || File size in KB, or number of data points for the current session.
|-
| '''Download''' || Download button for each individual log file.
|}

Below the table:
* '''Clear All Data''' — Deletes all stored log files. Requires confirmation.
* '''Remove Empty Logs''' — Cleans up zero-byte or near-empty files from aborted sessions.

Stored log files are downloaded as CSV for analysis. The dashboard's '''Download View''' button can additionally export the currently visible chart view as CSV, PNG, or SVG. CSV files use semicolon separation with dot as decimal divider.

'''Backup:''' Internal storage is not archival. Download data to a secure location regularly.

=== Device Management ===

==== Routine Maintenance ====

* '''Calibrate Device:''' Adjusts LED duty cycles. Required after each filter change.
* '''View System Status:''' Opens a structured status report for diagnosing issues. Entries are grouped by category: hardware, measurement, system, network.
* '''Download Logs:''' Downloads the structured system status report as a text file for troubleshooting or support.
* '''Identify Device:''' Blinks the device LED for about two minutes. Use this to find the right unit when more than one bcMeter is nearby.

==== System Operations ====

* '''Reboot Device:''' Restarts the device.
* '''Shutdown Device:''' Powers down before unplugging. Use this before disconnecting power. If the device loses power during an active session, it resumes measurement on the next boot.
* '''Manual Firmware Update:''' Opens a dialog to upload a firmware file. The device also checks for updates a few times a day.
* '''Factory Reset:''' Permanently erases all measurement logs, WiFi credentials, calibration data, and device settings. A slide-to-confirm gesture is required. The device reboots into factory state.

==== Firmware Update Notifications ====

When the device detects a newer firmware version, an '''Update Available''' modal appears showing:
* The new version number and current version
* Release notes (if available)
* '''Update Now''' button to apply the update immediately (with progress bar)
* '''Skip for now''' to dismiss and update later

Updates download over WiFi and are applied automatically. The device reboots after a successful update.

=== System Status ===

Shows device information:

* '''Device ID:''' Unique hardware identifier (MAC address).
* '''Software Version:''' Installed firmware version.
* '''Free Memory:''' Available system memory.
* '''Last Calibration:''' Timestamp of the most recent calibration.

=== Time Synchronization ===

Accurate timestamps need a correct device clock, especially on devices without internet access.

* '''Browser Time / Device Time:''' Displayed for comparison.
* '''Sync:''' If mismatch exceeds 10 seconds, a sync button appears to synchronize the device clock with your browser.

Devices connected to the internet sync automatically via NTP. Modem-based time sync (CLTS) is also supported when a 4G modem is connected.

=== Geolocation ===

When location services are active (Settings > Measurement > Location), the Geolocation card shows:

* '''Location:''' Latitude/longitude with source (GPS, cell tower, or IP-based) and accuracy indicator.
* '''Altitude (barometric):''' Derived from the pressure sensor.
* '''Altitude (GPS) & Speed:''' Shown when a GPS module is connected and has a fix.

The location input accepts common coordinate formats: <code>48.2082, 16.3738</code> — <code>48.2082 16.3738</code> — <code>(48.2082; 16.3738)</code>.

=== bcMeter (DIY) — Raspberry Pi ===

The following notes apply specifically to the '''bcMeter (DIY)''' Raspberry Pi version. For the commercial bcMeter (ESP32), the sections above describe all maintenance procedures.

==== Storage ====

The Raspberry Pi version stores measurement data on the Linux filesystem (typically under <code>/home/bcmeter/logs/</code>). There is no fixed flash storage limit — available disk space depends on the SD card and system configuration. The web interface data manager works the same way as on the ESP32: log files are listed and can be downloaded or deleted individually.

The Pi does '''not''' use LittleFS or NVS. Configuration is stored in <code>~/bcmeter/bcMeter_config.json</code>.

==== Service Management ====

The bcMeter software runs as a systemd service (<code>bcMeter.service</code>). '''Do not use <code>systemctl stop</code>''' — stopping the service also disables the WiFi access point, cutting off remote access. Use the web interface Reboot or Shutdown buttons, or <code>systemctl restart</code> if a restart is needed from the terminal.

The firmware update endpoint (<code>POST /api/update</code>) accepts a <code>.tar.gz</code> or <code>.zip</code> archive, extracts it over the code directory, and runs <code>sudo systemctl restart bcMeter.service</code> automatically.

==== Maintenance Log Bundle ====

The Raspberry Pi version provides an additional endpoint, <code>GET /api/maintenance-logs</code>, which downloads a zip bundle for support purposes. The bundle contains:

* Rotating <code>bcmeter.log</code> files
* Syslog and <code>dmesg</code> output
* The 10 most recent CSV session files
* <code>journalctl</code> output for the bcMeter and pigpiod services
* The current config JSON (sensitive keys redacted)
* The incident log

This endpoint does not exist on the ESP32, which uses the structured <code>/api/logs</code> endpoint and crash report email for equivalent diagnostics.

==== ADC Hardware ====

The Raspberry Pi version uses the ADS8344E (18-bit, SPI) or MCP3428 (I2C, legacy) ADC, rather than the ADS1220 used on the ESP32. Calibration and measurement procedures are identical from the user's perspective.

API reference

2026-06-08T18:59:35Z

Bcmwiki: Restructure: platform separation (ESP32 commercial prioritised, Raspberry Pi DIY in own section); verified against firmware/Pi source; complete serial command list

== API Reference ==

The bcMeter exposes a REST API on port 80. All endpoints are accessible without authentication when connected to the device network. CORS is enabled for all responses (<code>Access-Control-Allow-Origin: *</code>).

The device identifies its platform via the <code>"env"</code> field in <code>/api/status</code>: <code>"env": "esp32"</code> for bcMeter (commercial) and <code>"env": "pi"</code> for bcMeter (DIY / Raspberry Pi).

The software is source-available — freely available for private, educational and research use (CC BY-NC 4.0): [https://github.com/dahljo/bcmeter-pi github.com/dahljo/bcmeter-pi] (Pi / DIY version).

=== Status & Diagnostics ===

{| class="wikitable"
! Method !! Endpoint !! Description !! Platforms
|-
| GET || <code>/api/status</code> || Current measurement state, last sensor readings (BC, ATN, sensor/reference voltages, flow, filter loading), error codes, sample count, session active, WiFi mode/SSID/RSSI, internet flag, firmware version, OTA result flag, time-sync state. || Both
|-
| GET || <code>/api/system</code> || Hardware info: IP, MAC address, heap and PSRAM usage, flash usage, modem status and signal, GPS detail, barometric altitude, geolocation source, current time, cycle timing statistics. || Both
|-
| GET || <code>/api/logs</code> || Structured health report as JSON with sections: <code>hardware</code>, <code>measurement</code>, <code>system</code>, <code>network</code>, <code>incidents</code>. Each entry has <code>{k, v, s}</code> (key, value, status: ok/warn/error/info). || Both
|-
| GET || <code>/api/debug_mobile/status</code> || Returns modem debug email send progress (from email handler). || Both
|}

=== Measurement Control ===

All control is dispatched through a single endpoint with an <code>action</code> query parameter:

{| class="wikitable"
! Method !! Endpoint !! Description !! Platforms
|-
| GET || <code>/api/control?action=start</code> || Begin measurement session. Returns 409 if time not synced, 423 if never calibrated, 424 if calibration stale (>28 days). Add <code>&force=1</code> to override preflight checks. Optional <code>&indoor=0|1</code> for one-shot indoor/outdoor override. || Both
|-
| GET || <code>/api/control?action=stop</code> || Stop measurement and finalise session file. || Both
|-
| GET || <code>/api/control?action=calibrate</code> || Start optical calibration routine (returns 202 immediately — poll <code>/api/calibration</code> for progress). Requires sampling to be stopped. || Both
|-
| GET || <code>/api/calibration</code> || Calibration status: <code>{running, done, ok, elapsed_ms, log}</code>. || Both
|-
| GET || <code>/api/control?action=clear_error</code> || Reset error state to ERR_NONE. || Both
|-
| GET || <code>/api/control?action=identify</code> || Triggers LED identify blink pattern (Morse code "bcmeter", ~30 seconds). Useful for locating a specific device when multiple units are deployed. || Both
|-
| GET || <code>/api/control?action=debug_mobile</code> || Triggers modem debug email via Lambda. Requires modem present. Returns 409 if modem unavailable or already running. || Both
|-
| GET || <code>/api/control?action=synctime&ts=EPOCH&tz=IANA</code> || Sync device clock. <code>ts</code> = Unix timestamp, <code>tz</code> = IANA timezone string (e.g. <code>Europe/Berlin</code>). || Both
|-
| GET || <code>/api/control?action=cleardata</code> || Delete all stored log files. || Both
|-
| GET || <code>/api/control?action=reboot</code> || End session and reboot the device. || Both
|-
| GET || <code>/api/control?action=shutdown</code> || Safely shut down the device. || Both
|-
| GET || <code>/api/control?action=factory_reset</code> || Permanently erase all logs, WiFi credentials, calibration data, and settings. Reboots into factory state. || Both
|}

=== Configuration ===

{| class="wikitable"
! Method !! Endpoint !! Description !! Platforms
|-
| GET || <code>/api/config</code> || All settings as JSON. Each parameter includes type, value, label, tab, and description. || Both
|-
| POST || <code>/api/config</code> || Update settings. JSON body with key-value pairs. Accepts <code>{key: value}</code> or <code>{key: {value: ...}}</code> format. Only changed values need to be sent. || Both
|-
| POST || <code>/api/device/rename</code> || Set device name. Body: <code>{"name": "bcmeter-A3AB"}</code> (1–32 chars). Updates mDNS/hostname accordingly. || Both
|-
| GET || <code>/api/ap-security</code> || Hotspot security settings: <code>{secured: bool, password: str}</code>. || Both
|-
| POST || <code>/api/ap-security</code> || Update hotspot password. Body: <code>{"secured": true, "password": "..."}</code> (min 8 chars). || Both
|-
| POST || <code>/api/email/validate</code> || Validate email API key against the Lambda endpoint. Body: <code>{"api_key": "..."}</code>. Returns <code>{valid: bool, error: str}</code>. || Both
|}

=== WiFi Management ===

{| class="wikitable"
! Method !! Endpoint !! Description !! Platforms
|-
| GET || <code>/api/wifi/scan</code> || List nearby networks: <code>{scanning: bool, networks: [{ssid, rssi, secure}]}</code>. Add <code>?refresh=1</code> to trigger a new background scan. || Both
|-
| GET || <code>/api/wifi/status</code> || Current connection: <code>{mode, status, ssid, ip, rssi, quality (0-4), internet, timeSynced}</code>. || Both
|-
| POST || <code>/api/wifi</code> || Save WiFi credentials. Body: <code>{"ssid": "...", "pass": "..."}</code> (password min 8 chars). Initiates reconnect. || Both
|-
| POST || <code>/api/wifi/connect</code> || Save credentials and initiate background connection attempt (returns 202). Password must be 8–63 chars. Body: <code>{"ssid": "...", "pass": "..."}</code>. || Both
|-
| GET || <code>/api/wifi/connect/status</code> || Connection progress: <code>{state: 0-3, elapsed, log, mode, ip, ssid, device_name, hostname}</code>. States: 0=idle, 1=connecting, 2=success, 3=failed. Poll after POST to <code>/api/wifi/connect</code>. || Both
|-
| POST || <code>/api/wifi/delete</code> || Delete credentials and switch to AP mode (deferred 2s background switch). || Both
|-
| POST || <code>/api/wifi/scan/refresh</code> || Explicitly trigger a new WiFi scan (returns 202, or 409 if already scanning). || Both
|}

=== Data Management ===

{| class="wikitable"
! Method !! Endpoint !! Description !! Platforms
|-
| GET || <code>/api/csv</code> || Current session CSV data. Returns header-only if no active session. Add <code>?file=FILENAME</code> for archived files. || Both
|-
| GET || <code>/api/files</code> || List stored CSV logs: <code>[{name, size, lines, date}]</code> sorted newest first. Add <code>?name=FILENAME</code> to download a specific file. || Both
|}

=== Firmware Updates ===

{| class="wikitable"
! Method !! Endpoint !! Description !! Platforms
|-
| GET || <code>/api/ota/status</code> || Check if update available: <code>{available, version, notes, apply_state, apply_progress, apply_error}</code>. || Both
|-
| POST || <code>/api/ota/check</code> || Force check for new firmware. || Both
|-
| POST || <code>/api/ota/skip</code> || Skip current available update. || Both
|-
| POST || <code>/api/ota/apply</code> || Download and apply firmware update. Returns 409 if none pending. || Both
|-
| POST || <code>/api/update</code> || Direct firmware upload. ESP32: accepts a raw <code>.bin</code> file, flashes to the OTA partition, reboots. Pi: accepts a <code>.tar.gz</code> or <code>.zip</code> archive, extracts over the code directory, restarts the <code>bcMeter.service</code>. || Both
|}

=== Captive Portal ===

These endpoints handle captive portal detection on mobile devices and redirect to the main interface in AP mode:

{| class="wikitable"
! Endpoint !! Purpose
|-
| <code>/generate_204</code> || Android captive portal check
|-
| <code>/hotspot-detect.html</code> || Apple captive portal check
|-
| <code>/canonical.html</code> || Firefox captive portal check
|-
| <code>/ncsi.txt</code> || Windows captive portal check
|-
| <code>/success.txt</code> || Generic connectivity probe (returns <code>"success"</code>)
|}

=== Static Routes ===

{| class="wikitable"
! Path !! Description
|-
| <code>/</code> || Serves the SPA frontend
|-
| <code>/discover</code> || Standalone device discovery page
|-
| <code>/current_log.csv</code> || Legacy redirect to <code>/api/csv</code>
|}

=== bcMeter (DIY) — Raspberry Pi OS-level extras ===

The following endpoints exist '''only on the Raspberry Pi''' version. They use Linux system commands and are not applicable to the ESP32.

{| class="wikitable"
! Method !! Endpoint !! Description
|-
| GET || <code>/api/maintenance-logs</code> || Downloads a zip bundle containing: rotating bcmeter.log files, syslog, 10 newest CSV sessions, dmesg, journalctl output for bcmeter and pigpiod services, config JSON, incident log. Uses <code>journalctl</code> and <code>dmesg</code> — Linux only.
|}

Additionally, on the Pi:

* <code>/api/control?action=reboot</code> runs <code>sudo reboot</code> (Pi: <code>routes_control.py:151</code>)
* <code>/api/control?action=shutdown</code> runs <code>sudo shutdown -h now</code> (Pi: <code>routes_control.py:161</code>)
* <code>/api/control?action=synctime</code> sets the timezone via <code>sudo timedatectl set-timezone</code> (Pi: <code>routes_control.py:276</code>)
* <code>/api/device/rename</code> calls <code>sudo hostnamectl set-hostname</code> and restarts avahi (Pi: <code>bcmeter/identity.py:41</code>)
* <code>/api/update</code> runs <code>sudo systemctl restart bcMeter.service</code> after extracting the archive (Pi: <code>routes_update.py:134</code>)

The following endpoints exist only on the Pi and have no ESP32 equivalent:

{| class="wikitable"
! Method !! Endpoint !! Description
|-
| GET || <code>/api/qc/pi/report</code> || Pi QC test report as JSON.
|-
| GET || <code>/api/qc/pi/report.html</code> || Pi QC test report as HTML.
|-
| POST || <code>/api/qc/pi/start</code> || Start the Pi QC test sequence.
|-
| GET || <code>/api/qc/pi/status</code> || Pi QC test status.
|-
| GET || <code>/api/lab/run</code> || Lab/engineering raw ADC capture (Pi equivalent of ESP32 serial LAB mode).
|-
| GET || <code>/api/lab/info</code> || Lab session status.
|}

The following endpoints exist only on the '''ESP32''' and have no Pi equivalent:

{| class="wikitable"
! Method !! Endpoint !! Description
|-
| GET || <code>/api/sdfiles</code> || List CSV files on the SD card.
|-
| GET || <code>/api/crash</code> || Last crash/reset report from CrashReport module.
|-
| GET || <code>/api/coredump</code> || Stream the raw ELF coredump from the coredump flash partition. Add <code>?erase=1</code> to erase after download.
|-
| GET || <code>/api/modem/test</code> || Run modem AT diagnostic and return results as JSON.
|-
| POST || <code>/api/lab/start</code> || Start a lab ADC capture session (params: <code>led_ch</code>, <code>led_duty</code>, <code>pump_duty</code>, <code>pump_hz</code>).
|-
| POST || <code>/api/lab/stop</code> || Stop the lab capture session.
|-
| GET || <code>/api/lab/status</code> || Lab session status: active, pairs captured, LED/pump settings.
|-
| POST || <code>/api/raw_capture/enable</code> || Toggle raw ADC sample capture ring buffer (param: <code>on=0|1</code>).
|-
| GET || <code>/api/raw_capture/read</code> || Drain the raw capture ring buffer as binary float32 pairs (8 bytes each). <code>X-Dropped</code> header reports overflow count.
|-
| GET || <code>/api/qc/sensors</code> || Live SPS30 + env-sensor read for QC (409 while sampling).
|-
| GET || <code>/api/qc/diag</code> || Passive diagnostic snapshot: heap, PSRAM, uptime, reset reason, WiFi, modem state. No AT calls.
|-
| GET || <code>/api/qc/pump_ramp/status</code> || QC pump ramp test status.
|-
| GET || <code>/api/qc/led_880/status</code> || QC LED stability test status.
|}

=== Example: Start a Measurement ===

<pre>
# Sync time first
curl "http://bcmeter-XXXX.local/api/control?action=synctime&ts=$(date +%s)&tz=Europe/Berlin"

# Start measurement
curl "http://bcmeter-XXXX.local/api/control?action=start"

# Poll status
curl "http://bcmeter-XXXX.local/api/status"

# Download current data
curl "http://bcmeter-XXXX.local/api/csv" -o measurement.csv
</pre>

Serial commands

2026-06-08T18:59:35Z

Bcmwiki: Restructure: platform separation (ESP32 commercial prioritised, Raspberry Pi DIY in own section); verified against firmware/Pi source; complete serial command list

== Serial Commands ==

This page documents the USB serial command interface of the '''bcMeter''' (ESP32 commercial device).

'''Raspberry Pi (DIY) note:''' The Raspberry Pi version of bcMeter does '''not''' have a serial command protocol. All control and diagnostics on the Pi are handled through the HTTP API (see [[API reference]]). The information on this page applies exclusively to the bcMeter (ESP32).

Connect via USB-C at '''115200 baud''':

<pre>
# macOS / Linux
screen /dev/tty.usbmodem* 115200

# Or via minicom
minicom -D /dev/ttyACM0 -b 115200
</pre>

Commands are plain text, terminated with a newline. The serial interface is always available regardless of measurement or WiFi mode.

=== Status & Diagnostics ===

{| class="wikitable"
! Command !! Description
|-
| <code>status</code> || Compact one-liner: state, init step, error, BC, ATN, sensor/reference voltages, flow, pump duty, filter loading, sample count.
|-
| <code>status json</code> || Same data as a JSON object — suitable for scripting and QC tooling.
|-
| <code>system</code> || Firmware version, env, free heap, PSRAM usage, flash usage, WiFi mode/SSID/IP/RSSI, MAC address, time-sync state.
|-
| <code>sensors</code> || Live read of all peripheral sensors: pump flow + duty + airflow voltage + bias, temperature/humidity/pressure (BME280 or SHT4x), GPS fix (if present), SPS30 PM values (if present).
|-
| <code>pumpinfo</code> || Detailed pump diagnostics: duty, flow (L/min), airflow voltage, bias, target flow, recovering flag, failed flag.
|-
| <code>logs [N]</code> || Print the last N incident log entries (default: all). Newest first.
|-
| <code>crash</code> || Last reset reason and crash report JSON (if a watchdog/panic crash was recorded on previous boot).
|-
| <code>ver</code> / <code>version</code> || Firmware version string and environment tag (prod/dev).
|-
| <code>bcm:probe</code> || Machine-readable JSON identity probe for QC tooling: device name, MAC, firmware version, environment, uptime. Output is a single line prefixed for easy grep/parse.
|-
| <code>cfg</code> || Quick display of key config values: <code>mail_logs_to</code>, <code>onboarding_step_one/two</code>, <code>device_name</code>, <code>send_log_by_mail</code>.
|-
| <code>STATUS</code> (caps) || Machine-readable one-liner for QC scripts: <code>OK sampling=... serLab=... adcPresent=... debug=... version=...</code>
|}

=== Measurement & Calibration ===

{| class="wikitable"
! Command !! Description
|-
| <code>start</code> || Start measurement. Fails with an error message if time is not synced. Use <code>start force</code> to override the time-sync check.
|-
| <code>start force</code> || Start measurement unconditionally (bypasses time-sync guard).
|-
| <code>stop</code> || Stop measurement.
|-
| <code>calibrate</code> || Start optical calibration (same routine as the web UI). Requires sampling to be stopped.
|-
| <code>clear_error</code> / <code>clearerr</code> || Reset the error state to ERR_NONE.
|-
| <code>identify</code> || Start LED identify blink pattern (Morse "bcmeter", ~30 s). Used to locate a specific device.
|-
| <code>identify_stop</code> / <code>identifystop</code> || Stop the identify blink.
|-
| <code>tempcal</code> || Toggle temperature calibration routine. If already running, stops it. Requires sampling stopped.
|-
| <code>factory_reset</code> || Mirror of <code>/api/control?action=factory_reset</code>: stops sampling, erases all logs and config, reboots into factory state. Used by QC provisioning workflow.
|}

=== Configuration — Read & Write ===

{| class="wikitable"
! Command !! Description
|-
| <code>get <key></code> || Print a single config key with its type and current value.
|-
| <code>set <key> <value></code> || Write a string config key to NVS. Special handling for <code>onboarding_step_one</code> / <code>onboarding_step_two</code> (stored as bool).
|-
| <code>setint <key> <value></code> || Write an integer config key.
|-
| <code>setfloat <key> <value></code> || Write a float config key.
|-
| <code>setbool <key> <true|false></code> || Write a bool config key. Accepts <code>1</code>, <code>true</code>, <code>on</code>, <code>yes</code> as true.
|-
| <code>cfgall [prefix]</code> || Dump all config entries, optionally filtered by key prefix.
|-
| <code>cfgjson</code> || Dump entire config as a JSON object (same structure as <code>/api/config</code>).
|}

=== Time Configuration ===

{| class="wikitable"
! Command !! Description
|-
| <code>settime <epoch></code> || Inject wall time (POSIX epoch seconds). Refuses values before 2023-11-14. Used when NTP is not available.
|-
| <code>settz <POSIX TZ></code> || Set the POSIX timezone string, e.g. <code>CET-1CEST,M3.5.0/2,M10.5.0/3</code>. Persists to NVS and applies immediately.
|}

=== Hardware Diagnostics ===

{| class="wikitable"
! Command !! Description
|-
| <code>led <ch> <duty></code> || Set LED brightness. Channel 0–2 (880 / 520 / 370 nm), duty 0–255. Turns the channel on immediately.
|-
| <code>pump <duty></code> || Set pump PWM duty cycle (0–255). Use <code>pumplock on</code> first to prevent the control task from overriding this.
|-
| <code>pumplock on</code> || Hand pump control to the serial operator — the automatic pump control task yields while locked.
|-
| <code>pumplock off</code> || Restore automatic pump control.
|-
| <code>adc</code> || Detect ADS1220 ADC and print current raw channel values. Reports "ADC OK" or "ADC not detected".
|-
| <code>sps30</code> || One-shot read from SPS30 particulate matter sensor. Returns PM2.5 and PM10 in µg/m³.
|-
| <code>gps</code> || GPS status: fix validity, satellite count, HDOP, latitude/longitude, altitude, speed, date/time.
|}

=== WiFi ===

{| class="wikitable"
! Command !! Description
|-
| <code>wifi</code> || Current WiFi state: mode (AP/STA), SSID, IP address, RSSI, internet reachability, time-sync status.
|-
| <code>scan</code> || Scan for nearby WiFi networks, print SSID, RSSI, and open/secured flag.
|-
| <code>connect <ssid> <password></code> || Save WiFi credentials to NVS and initiate connection.
|-
| <code>ap</code> || Switch to access-point (hotspot) mode.
|-
| <code>wificlear</code> || Delete stored WiFi credentials and force AP mode. Used in QC to ensure the 4G modem test cannot fall back to WiFi.
|}

=== Modem / 4G ===

{| class="wikitable"
! Command !! Description
|-
| <code>modem <AT command></code> || Send a raw AT command to the SIM7080G modem and print the response. Requires modem to be powered on first.
|-
| <code>modemscan</code> || Scan UART configurations to detect modem baud rate and port.
|-
| <code>modemon</code> || Power on and initialise the modem.
|-
| <code>modemoff</code> || Power off the modem.
|-
| <code>debugmobile</code> || Trigger the debug-mobile email send (same as <code>/api/control?action=debug_mobile</code>). Sends a diagnostic email via the 4G modem.
|-
| <code>modemlog</code> || Synchronously trigger the modem log streaming path (chunked upload to Lambda). Prints OK/FAIL.
|-
| <code>postest <url> <size></code> || POST a padded test payload of the given byte size to a URL via the modem. Used to verify HTTP POST framing over 4G. Lambda responds 200 to <code>_coap_test</code> payloads.
|}

=== Storage & Session ===

{| class="wikitable"
! Command !! Description
|-
| <code>storage</code> || Show LittleFS usage (used/total bytes), SD card presence, active session filename, and write-buffer depth.
|-
| <code>export</code> || Export all log files to SD card.
|-
| <code>startsess</code> || Manually start a new storage session (creates a new CSV file).
|-
| <code>endsess</code> || Manually end the current storage session.
|-
| <code>loginfo</code> || Print current session filename, file size, remote-sent offset, session-active flag, and free heap.
|-
| <code>dellog <filename|current></code> || Delete a named log file, or the current session if <code>current</code> is given.
|-
| <code>gentest <KB></code> || Write a synthetic CSV log of the given size (1–1024 KB) for storage stress-testing.
|-
| <code>resetoffset</code> || Reset the remote-sent byte offset to 0 (forces re-upload of the current session on the next mail cycle).
|-
| <code>reset</code> || Reboot the device.
|}

=== Email & QC ===

{| class="wikitable"
! Command !! Description
|-
| <code>testemail [4g]</code> || Send a test status email. Without <code>4g</code>, sends via WiFi/Lambda. With <code>4g</code>, forces 4G modem path. Recipient is <code>mail_logs_to</code> (falls back to <code>jd@bcmeter.org</code>).
|-
| <code>qcemail <type> <json></code> || Send a QC result email via 4G modem. <code>type</code> is the email subject key; <code>json</code> is the JSON payload. Used by the provisioning QC workflow.
|}

=== Lab / Engineering Mode ===

These commands are used during hardware characterisation and manufacturing tests. They require no special mode to be active — they are always available.

{| class="wikitable"
! Command !! Description
|-
| <code>PING</code> || Responds <code>PONG\n</code>. Used by QC scripts to verify serial connectivity.
|-
| <code>LAB <ch> <led_duty> <pump_duty> <pump_hz> <n_pairs></code> || Run a lab ADC capture session: set LED channel/duty and pump duty/frequency, capture N raw ADC pairs, return binary data over serial.
|-
| <code>STREAM <ch> <led_duty> <led_hz> <target_ml> <pump_hz> <duration_s></code> || Streaming lab mode: continuous ADC pairs with airflow control for the given duration.
|-
| <code>LABFLOW <ch> <led_duty> <led_hz> <target_ml> <pump_hz> <n_pairs></code> || Lab mode with airflow target: capture N pairs at controlled flow rate.
|-
| <code>LABEND</code> || End the current lab session. Responds <code>OK\n</code>.
|-
| <code>STOP</code> || Acknowledge stop. Used by QC scripts as a generic stop/sync marker.
|-
| <code>SILENCE on</code> || Suppress serial log output during lab capture (reduces USB-CDC overhead).
|-
| <code>SILENCE off</code> || Re-enable serial log output.
|-
| <code>ADCMODE <0–6></code> || Set ADS1220 data rate: 0=20, 1=45, 2=90, 3=175, 4=330, 5=600+turbo (→1200), 6=1000+turbo (→2000) SPS.
|}

=== Debug Isolation (MUTE) ===

Used to isolate audible or electrical noise sources by progressively silencing PWM and RF emitters.

{| class="wikitable"
! Command !! Description
|-
| <code>MUTE status on</code> || Pause the status LED task (pin to high-Z). Reversible without reset.
|-
| <code>MUTE status off</code> || Resume the status LED task.
|-
| <code>MUTE leds</code> || Detach all three measurement LED PWM channels (requires <code>reset</code> to restore).
|-
| <code>MUTE pump</code> || Detach the pump PWM channel (requires <code>reset</code> to restore).
|-
| <code>MUTE wifi</code> || Disconnect WiFi and turn off the radio (requires <code>reset</code> to restore).
|}

=== General ===

{| class="wikitable"
! Command !! Description
|-
| <code>help</code> || Print a grouped command summary to the serial console.
|}

=== Usage Examples ===

<pre>
# Check device status
> status
[Status] state=idle(0) init=0:... err=0:OK bc=0.0 atn=0.000 ...

# Start measurement (after syncing time via the web UI)
> start
OK sampling started

# Read live sensor snapshot
> sensors
[Pump] flow=0.3001 LPM duty=80 v=1.234 bias=0.002
[Env] T=22.50°C H=48.3% P=1013.2 hPa
[GPS] fix=YES sats=7 hdop=1.2 52.463100,13.306900 alt=48m

# Manually test pump at a fixed duty (lock first to prevent auto-override)
> pumplock on
OK pump locked — controlTask yielding
> pump 120
Pump set to 120
> pumpinfo
[Pump] duty=120 flow=0.4210 ...
> pumplock off
OK pump unlocked

# Set device timezone
> settz CET-1CEST,M3.5.0/2,M10.5.0/3
OK tz=CET-1CEST,M3.5.0/2,M10.5.0/3

# Probe via QC tooling
> bcm:probe
{"_bcm":1,"schema":"probe/v1","name":"bcmeter-A1B2","mac":"AA:BB:CC:DD:EE:FF","fw":"1.5.230","env":"prod","up":3721}
</pre>

Developer mode

2026-06-08T18:47:40Z

Bcmwiki: Consistency pass 2: airflow range via Configuration, multi-wavelength as in-development, ESP32/Pi CSV filename split, legacy sensor wording

== Developer Mode ==

The bcMeter interface has a hidden developer mode for hardware tuning and diagnostics. '''Changes in developer mode affect hardware directly''' and can make measurements unusable when set incorrectly. Use it only for support, development, or device-specific provisioning.

=== Activating Developer Mode ===

# Open '''Settings'''.
# Click the '''device name''' text next to "Configuration" '''7 times within 3 seconds'''.
# The name changes to include <code>[DEV]</code>.
# A new '''⚠ Dev''' tab appears in the settings panel.

Developer mode is active for the current page session and is reset when the page is reloaded.

=== Developer Tab Layout ===

The Developer tab opens with a warning banner:

<blockquote style="background:#fff3cd;padding:8px 16px;border-radius:4px;">Developer mode — changes affect hardware directly. Save only if you know what you are doing.</blockquote>

Settings are grouped by namespace. The values below match the current ESP32 firmware defaults in <code>cfgstore.cpp</code>.

==== BC Smoothing Algorithm ====

The first control selects the BC smoothing algorithm. This setting is stored as <code>bc_filter</code>.

{| class="wikitable"
! Value !! Description
|-
| <code>median3</code> (default) || 3-sample median filter. Good default for rejecting isolated outliers.
|-
| <code>ema</code> || Exponential moving average. Smoother trend, slower response to abrupt changes.
|-
| <code>kalman</code> || Adaptive Kalman-style smoothing based on signal dynamics.
|}

==== Calibration (<code>dev:calibration</code>) ====

{| class="wikitable"
! Parameter !! Description !! Default
|-
| <code>sample_spot_diameter</code> || Sample spot diameter in cm. Used in BC mass concentration calculations. || 0.4
|-
| <code>filter_scattering_factor</code> || Filter scattering factor used by the optical correction model. || 1.39
|-
| <code>device_specific_correction_factor</code> || Per-device correction factor from lab comparison or provisioning. || 1.0
|}

==== Optical (<code>dev:optical</code>) ====

{| class="wikitable"
! Parameter !! Description !! Default
|-
| <code>burst_measurement</code> || LED is only enabled during the final seconds of a sample cycle. Experimental power/thermal mode. || false
|-
| <code>adc_block_samples</code> || ADC samples per sensor/reference block. Higher values reduce noise and increase capture time. || 256
|-
| <code>led_duty_cycle_370nm</code> || UV LED brightness/PWM duty for 370 nm channel. || 255
|-
| <code>led_duty_cycle_520nm</code> || Green LED brightness/PWM duty for 520 nm channel. || 255
|-
| <code>led_duty_cycle_880nm</code> || IR LED brightness/PWM duty for 880 nm channel. || 100
|-
| <code>cal_k_370nm</code> || Calibration factor for the 370 nm channel. || 1.0
|-
| <code>cal_k_520nm</code> || Calibration factor for the 520 nm channel. || 1.0
|-
| <code>cal_k_880nm</code> || Calibration factor for the 880 nm channel. || 1.0
|-
| <code>shadow_factor</code> || Weingartner shadow factor. Typical examples: 1.1 diesel, 1.2 urban, 1.5 biomass. || 1.2
|}

==== Pump (<code>dev:pump</code>) ====

{| class="wikitable"
! Parameter !! Description !! Default
|-
| <code>pump_dutycycle</code> || Base pump power/PWM duty. || 20
|-
| <code>max_pump_duty</code> || Maximum pump duty cycle. || 255
|-
| <code>min_pump_duty</code> || Minimum pump duty cycle. || 1
|-
| <code>min_airflow_ml</code> || Minimum airflow before stall recovery starts, in ml/min. || 70
|-
| <code>twelvevolt_duty</code> || 12V pump output duty cycle. || 20
|-
| <code>reverse_dutycycle</code> || Reverse pump duty-cycle handling for hardware variants. || false
|-
| <code>disable_pump_control</code> || Disable internal pump control loop. Use only with external control hardware. || false
|-
| <code>TWELVEVOLT_ENABLE</code> || Enable 12V power output. || false
|-
| <code>log_pump_duty</code> || Write pump duty cycle into the CSV per sample. || false
|}

==== Auto Flow Control (<code>dev:afc</code>) ====

{| class="wikitable"
! Parameter !! Description !! Default
|-
| <code>afc_bc_low</code> || BC concentration below which AFC moves toward maximum flow. || 300 ng/m³
|-
| <code>afc_bc_high</code> || BC concentration above which AFC moves toward minimum flow. || 2000 ng/m³
|-
| <code>afc_flow_low</code> || Minimum airflow when AFC is active. || 0.05 L/min
|-
| <code>afc_flow_high</code> || Maximum airflow when AFC is active. || 0.7 L/min
|-
| <code>afc_slope_gain</code> || Flow boost per 100 ng/min downward BC trend. || 0.05
|}

==== Hardware (<code>dev:hardware</code>) ====

{| class="wikitable"
! Parameter !! Description !! Default
|-
| <code>airflow_sensor</code> || Airflow sensor is installed and should be used. || true
|-
| <code>af_sensor_type</code> || Airflow sensor type: 0 = P0001A1, 1 = P0010A2. || 1
|-
| <code>enable_wifi</code> || WiFi connectivity is available. || true
|-
| <code>iot_enable</code> || 4G / IoT modem connectivity is available. || true
|-
| <code>show_undervoltage_warning</code> || Show warning when the optical 12V rail / ADC is not detected. || false
|}

==== System (<code>dev:system</code>) ====

{| class="wikitable"
! Parameter !! Description !! Default
|-
| <code>num_channels</code> || Number of optical wavelength channels. || 1
|-
| <code>is_ebcMeter</code> || Direct emission measurement mode. Changes units and emission-oriented behavior. || false
|-
| <code>device_name</code> || Device hostname/name used for mDNS and UI display. || bcMeter
|-
| <code>heating</code> || Enable heating hardware if installed. || false
|-
| <code>use_display</code> || Device has an attached display. || false
|-
| <code>email_service_password</code> || Mail service password for DIY/development devices. Provisioned devices normally already have this set. || email_service_password
|-
| <code>onboarding_step_one</code> || Phase 1 onboarding complete: contact email and WiFi setup. || false
|-
| <code>onboarding_step_two</code> || Phase 2 onboarding complete: calibration and data sharing choice. || false
|-
| <code>onboarding_email_sent</code> || Welcome/access email has already been sent. || false
|-
| <code>team_upload_interval</code> || Cloud/team upload interval in hours when data sharing is enabled. || 1
|-
| <code>bcmeter_team_email</code> || Contact email used for bcMeter team workflows. || empty
|-
| <code>last_cal_time</code> || Timestamp of the last successful calibration. || never
|}

=== Onboarding State ===

The current firmware stores onboarding progress with separate flags:

* <code>onboarding_step_one</code>: WiFi/email phase completed.
* <code>onboarding_step_two</code>: calibration/data-sharing phase completed.
* <code>onboarding_email_sent</code>: welcome email has already been sent.

The browser also uses local storage and cookies for temporary "Skip for now" behavior. "Don't show again" writes the matching onboarding step flag to the device.

=== Development Build Detection ===

When the device is running a development build, the status API returns <code>"env":"dev"</code>. The interface shows a red banner:

<blockquote style="background:#dc3545;color:#fff;padding:8px 16px;border-radius:4px;">DEVELOPMENT BUILD — connected to dev backend</blockquote>

=== 12V Power Warning ===

If the optical ADC is not detected, the interface can show a 12V warning:

<blockquote style="background:#fff3cd;padding:8px 16px;border-radius:4px;">'''⚠ 12V Power Missing''' — The optical ADC is not detected. Optics and light sensors will not function. Pump and airflow control may be limited by hardware state.</blockquote>

=== Platform Variants (DIY / open line vs assembled instruments) ===

The <code>bcmeter-dev</code> Raspberry Pi codebase powers '''bcMeter (DIY)''' builds, but it differs from the ESP32 firmware in the assembled instruments. Device-specific differences should be treated as implementation details of the same function:

* '''Networking:''' Raspberry Pi builds use FastAPI/uvicorn and NetworkManager, while ESP32 builds use the embedded web server and ESP-IDF WiFi stack.
* '''Optics/ADC:''' Pi builds use ADS8344E hardware (legacy units may use MCP342X); ESP32 builds use ADS1220-based optical acquisition.
* '''Firmware updates:''' bcMeter (DIY) builds may update through OS/GitHub release workflows, while ESP32 devices use OTA firmware images.
* '''Sensors:''' Some legacy or prototype DIY builds expose additional sensors (e.g. DS18B20 1-Wire temperature) not present on standard units.

CSV data format

2026-06-08T18:47:40Z

Bcmwiki: Consistency pass 2: airflow range via Configuration, multi-wavelength as in-development, ESP32/Pi CSV filename split, legacy sensor wording

== CSV Data Format ==

bcMeter stores measurement data as CSV files. This page documents the file format and column definitions.

=== File Format ===

{| class="wikitable"
! Property !! Value
|-
| Delimiter || Semicolon (<code>;</code>)
|-
| Encoding || UTF-8
|-
| Decimal separator || Dot (<code>.</code>)
|-
| Line ending || LF (<code>\n</code>)
|-
| First row || Column headers
|}

=== Filename Convention ===

* Active session: <code>YY-MM-DD_HHMMSS.csv</code> on ESP32 builds, <code>DD-MM-YY_HHMMSS.csv</code> on Raspberry Pi builds (based on session start time)
* Fallback (no RTC sync): <code>nosync_HHMMSS.csv</code> (based on uptime)

=== Column Definitions ===

==== Core Columns (always present) ====

{| class="wikitable"
! Column !! Type !! Unit !! Description
|-
| <code>bcmDate</code> || string || DD-MM-YY || Measurement date
|-
| <code>bcmTime</code> || string || HH:MM:SS || Measurement time
|-
| <code>bcmRef_880nm</code> || float || V || Reference channel voltage (880nm LED through clean filter)
|-
| <code>bcmSen_880nm</code> || float || V || Sensor channel voltage (880nm LED through sample spot)
|-
| <code>bcmATN_880nm</code> || float || — || Attenuation at 880nm = −100·ln(Sen/Ref), dimensionless. The absorption cross-section σ enters the BC concentration, not ATN.
|-
| <code>BCngm3_unfiltered_880nm</code> || float || ng/m³ || Real-time BC concentration (unsmoothed)
|-
| <code>BCngm3_880nm</code> || float || ng/m³ || BC concentration with rolling average applied
|-
| <code>relativeLoad</code> || float || % || Filter loading (0 = clean, 100 = saturated)
|-
| <code>AAE</code> || float || — || Ångström Absorption Exponent (requires multi-wavelength)
|-
| <code>Temperature</code> || float || °C || Internal device temperature
|-
| <code>airflow</code> || float || L/min || Measured airflow rate
|}

==== Multi-Wavelength Columns (in development, not in shipped hardware) ====

Same structure as 880nm, repeated for each wavelength:

* <code>bcmRef_520nm</code>, <code>bcmSen_520nm</code>, <code>bcmATN_520nm</code>, <code>BCngm3_unfiltered_520nm</code>, <code>BCngm3_520nm</code>
* <code>bcmRef_370nm</code>, <code>bcmSen_370nm</code>, <code>bcmATN_370nm</code>, <code>BCngm3_unfiltered_370nm</code>, <code>BCngm3_370nm</code>

==== Environmental Columns (optional, sensor-dependent) ====

{| class="wikitable"
! Column !! Type !! Unit !! Description
|-
| <code>humidity</code> || float || % || Relative humidity (BME280/SHT4x)
|-
| <code>hPa</code> || float || hPa || Atmospheric pressure (BME280)
|-
| <code>PM2.5</code> || float || µg/m³ || Particulate matter <2.5µm (SPS30)
|-
| <code>PM10</code> || float || µg/m³ || Particulate matter <10µm (SPS30)
|}

==== GPS Columns (optional, if GPS module connected and has fix) ====

{| class="wikitable"
! Column !! Type !! Unit !! Description
|-
| <code>lat</code> || float || degrees || Latitude (WGS84)
|-
| <code>lon</code> || float || degrees || Longitude (WGS84)
|-
| <code>altitude</code> || float || m || GPS altitude above sea level
|}

==== Metadata Columns ====

{| class="wikitable"
! Column !! Type !! Description
|-
| <code>notice</code> || string || System notices or warnings per data point
|-
| <code>sampleDuration</code> || float || Actual measurement duration for this sample (seconds)
|-
| <code>notes</code> || string || User-added annotations
|}

=== Example Data ===

<pre>
bcmDate;bcmTime;bcmRef_880nm;bcmSen_880nm;bcmATN_880nm;BCngm3_unfiltered_880nm;BCngm3_880nm;relativeLoad;AAE;Temperature;airflow
04-03-26;19:37:09;0.9679;0.9321;3.76;1686;1686;0;0;0;0.4659
04-03-26;19:42:09;0.9745;0.9335;4.3;4028.5;1686;0;0;0;0.3088
04-03-26;19:47:09;0.9752;0.9315;4.59;2371.4;1830.2;0;0;0;0.2832
</pre>

=== Import Notes ===

* '''Excel:''' Use "Text Import Wizard" and set delimiter to semicolon. The date format DD-MM-YY may need manual conversion.
* '''Python/Pandas:''' <code>pd.read_csv('file.csv', sep=';')</code>
* '''R:''' <code>read.csv2('file.csv')</code> (uses semicolon by default)

Interface

2026-06-08T18:47:40Z

Bcmwiki: Consistency pass 2: airflow range via Configuration, multi-wavelength as in-development, ESP32/Pi CSV filename split, legacy sensor wording

== Web Interface Overview ==

The bcMeter web interface is a local dashboard for measurement data, device control, and settings. Open it from a browser on the same network as the device.

'''Try the live demo:''' [https://bcmeter.org/demo/ bcmeter.org/demo]

=== Dashboard Elements ===

The main screen has five areas:

# '''Control Bar''' — Buttons to Start/Stop measurement, access Log Files, Settings, and Maintenance. On mobile or narrow screens, the bar collapses into a hamburger menu (☰).
# '''Status Panel''' — Device state (with color-coded status dot), filter loading indicator, and time synchronization status.
# '''Statistics''' — 1h Average, Session Average, and Peak Value. The Peak Value card includes the timestamp of the peak and a '''Reset''' button.
# '''Live Plot''' — Black Carbon concentration over time.
# '''Plot Controls''' — Download, zoom reset, axis scaling, log selection, Y-axis assignment, resampling, and denoising.

==== Dark Mode ====

A dark mode toggle (moon/sun icon) is in the top-right corner of the navigation bar. The preference is saved in the browser.

=== Status Indicators ===

==== Device Status ====

{| class="wikitable"
! Status !! Meaning
|-
| '''Ready''' || Device is idle. Pump is off.
|-
| '''Initializing''' || Pump is priming and the optical chamber is warming up. Data is not yet recorded.
|-
| '''Running''' || Active measurement. Data is being saved.
|-
| '''Error''' || System error detected. Open System Status or download logs in the Maintenance menu.
|}

==== Time Sync Status ====

The status bar shows whether the device clock is synced. If it shows "Time: not synced" in red, use '''Maintenance > Time Synchronization''' to sync the device clock with your browser.

==== Filter Loading Status ====

The "Filter" indicator shows how much of the filter strip is loaded. The color changes with loading level:

{| class="wikitable"
! Color !! Loading !! Meaning
|-
| style="background:#28a745;color:#fff" | '''Green''' || 0–30% || Filter is clean. Signal quality is optimal.
|-
| style="background:#ffc107" | '''Orange''' || 30–70% || Loading increasing. Mathematical compensation is active. Prepare a replacement.
|-
| style="background:#dc3545;color:#fff" | '''Red''' || 70–85% || Heavily loaded. Compensation becomes less reliable. Replace soon. Email alert sent every 12h when >70%.
|-
| style="background:#343a40;color:#fff" | '''Dark''' || 85%+ || Near saturation. Replace immediately.
|}

==== Alert Modals ====

The interface opens alert modals for these measurement conditions:

* '''Filter Loading High''' — Filter loading exceeds the configured threshold. Replace the filter paper soon.
* '''No Airflow Detected''' — Appears when airflow drops to near zero during measurement. Check pump tubing and connections.
* '''High Humidity''' — Warning when humidity inside the device is too high.
* '''Low Disk Space''' — Warning when internal storage is running low.

These alerts appear once per condition and can be dismissed with "Got it."

=== Data Visualization ===

==== Plot Behavior ====

The graph shows measurements as a time series. The optical signal is analog, so the raw line is usually jagged. Smoothed values show the trend more clearly.

After starting a measurement, the graph needs about 3–4 samples before it appears. At the default 300s (5 min) sample interval, first data appears after 15–20 minutes.

* '''Zoom:''' Click and drag to zoom in. Double-click to reset.

==== Plot Controls ====

Below the live plot:

* '''Download View:''' Export current view as CSV, PNG, or SVG.
* '''Reset Zoom:''' Restore default view after zooming.
* '''Axis Scaling:''' Manually override automatic Y-axis scaling (min/max per axis) when peaks compress the view.

==== View Log ====

Dropdown for the current session or a previous log file stored on the device.

==== Y-Axis Controls ====

Each axis row (Y1, Y2, and added axes) includes:

* '''Toggle switch''' — Show or hide the axis on the chart.
* '''Variable selector''' — Choose which parameter to display (see [[Interface#Plot Parameters|Plot Parameters]]).
* '''Resample slider''' — Averages consecutive samples before plotting. "Off" shows every sample; higher values reduce visual noise and data density.
* '''Denoise mode''' — Segmented control with four options:
** '''Raw''' — Unfiltered signal, showing every data point as-is.
** '''Med''' — Median filter (default, highlighted in teal). Good default noise reduction.
** '''EMA''' — Exponential Moving Average. Gives more weight to recent values, good for tracking trends.
** '''ONA''' — Optimized Noise Average.
* '''Denoise slider''' — Adjusts the strength/window size for the selected denoise mode. The number next to the slider shows the current value.
** ''Direct emission monitoring:'' Keep below 4 for fast response.
** ''Ambient monitoring:'' Higher values are acceptable when a smoother trend is more important than fast response.

==== Adding Extra Axes ====

Click '''+ Add axis''' below Y2 to add more Y-axes. Each extra axis has the same controls. Use extra axes to compare values such as BC concentration, temperature, and airflow in one chart.

=== Plot Parameters ===

These parameters can be assigned to any Y-axis:

{| class="wikitable"
! Parameter !! Description
|-
| '''Reference (880nm)''' || Light intensity from the 880nm LED through the clean portion of the filter — baseline for comparison. Optional 520nm / 370nm channels are in development (not available in shipped hardware).
|-
| '''Sensor (880nm)''' || Light intensity after passing through the particle-loaded spot.
|-
| '''Attenuation (880nm)''' || Calculated reduction in light intensity caused by absorbing particles.
|-
| '''BC Unfiltered (880nm)''' || Real-time black carbon concentration without smoothing.
|-
| '''Black Carbon (880nm)''' || BC concentration in ng/m³, with rolling average applied.
|-
| '''Relative Load''' || Filter spot saturation level (%), indicating when replacement is needed.
|-
| '''Ångström Exponent''' || Ratio indicating aerosol source characteristics (requires multi-wavelength hardware — in development, not in shipped devices).
|-
| '''Temperature (°C)''' || Internal operating temperature — important for measurement stability.
|-
| '''Humidity (%)''' || Relative humidity inside the device (if sensor equipped).
|-
| '''Air Flow (l/min)''' || Current airflow rate through the filter (if flow sensor equipped).
|}

Best practices

2026-06-08T18:47:40Z

Bcmwiki: Consistency pass 2: airflow range via Configuration, multi-wavelength as in-development, ESP32/Pi CSV filename split, legacy sensor wording

== Best Practices ==

=== Environment ===

* Keep the device '''away from direct sunlight''', radiators, and fireplaces — it is sensitive to temperature and lighting changes.
* Position the inlet away from localized emission sources unless intentionally measuring them.
* For indoor use, avoid placement near HVAC vents or drafts.

=== Sampling Configuration ===

* '''Sample frequency:'''
** Ambient immission monitoring: '''180–600 seconds''' (3–10 min)
** Direct emissions from wood stoves (µg vs ng range): '''10–30 seconds'''
** Note: increasing frequency may increase noise.

* '''Airflow:'''
** Default 300 mL/min, adjustable (see [[Configuration]] for the range). Higher flow improves signal but loads the filter faster; the usable range narrows as the filter loads. With Auto Flow Control the device sets the rate automatically from the measured BC concentration.
** Higher airflow improves signal strength but loads the filter faster.

{| class="wikitable"
! Pollution Level !! Daily Avg BC !! Recommended Airflow
|-
| Heavy pollution || >2000 ng/m³ || 50 mL/min
|-
| Typical urban || ~500 ng/m³ || 100–250 mL/min
|-
| Low pollution || <500 ng/m³ || 300–400 mL/min
|}

When '''Auto Flow Control''' is enabled, the device adjusts airflow automatically based on measured BC concentration — reducing flow when BC is high (to extend filter life) and increasing flow when BC is low (for better signal).

=== Signal Quality ===

Signal-to-noise ratio improves with:
* Higher BC loads
* Higher air volume per sample
* Smaller sample spot diameter

'''Filtering:''' Apply median/average filtering (denoise slider) to reduce noise. The rolling average is closer to the "real" value than individual data points.

'''Calibration:''' Always calibrate after every filter change for reliable filter status indication and accurate measurement.

=== Filter Management ===

* At the default airflow in a typical urban environment (~500 ng/m³), a filter lasts approximately '''3–5 days'''.
* In heavily polluted areas, a filter may saturate in '''6–12 hours'''.
* Filter status is derived from attenuation (ATN): measurements are fully quantitative up to about ATN 75 and degrade at higher loading; the device flags the filter for replacement around ATN 120. (The ATN value is not a simple percentage of light loss.)
* The [[Configuration#Measurement Tab|Airflow Reference table]] in Settings helps estimate filter lifetime for your conditions.

=== Supported Filter Papers ===

{| class="wikitable"
! Filter Paper !! Scattering Correction Factor
|-
| Pall T60A20 || 1.0
|-
| AE33 Filter || 0.75
|-
| AE51 Filter || 1.0
|}

Other filter papers can be supported by determining their scattering factor. Send a sample to jd@bcmeter.org for calibration.

Developer mode

2026-06-08T18:43:41Z

Bcmwiki: Consistency pass: multi-wavelength in-development, bcmeter-pi link, anchor/Flask/V2 fixes, airflow & ATN clarifications

== Developer Mode ==

The bcMeter interface has a hidden developer mode for hardware tuning and diagnostics. '''Changes in developer mode affect hardware directly''' and can make measurements unusable when set incorrectly. Use it only for support, development, or device-specific provisioning.

=== Activating Developer Mode ===

# Open '''Settings'''.
# Click the '''device name''' text next to "Configuration" '''7 times within 3 seconds'''.
# The name changes to include <code>[DEV]</code>.
# A new '''⚠ Dev''' tab appears in the settings panel.

Developer mode is active for the current page session and is reset when the page is reloaded.

=== Developer Tab Layout ===

The Developer tab opens with a warning banner:

<blockquote style="background:#fff3cd;padding:8px 16px;border-radius:4px;">Developer mode — changes affect hardware directly. Save only if you know what you are doing.</blockquote>

Settings are grouped by namespace. The values below match the current ESP32 firmware defaults in <code>cfgstore.cpp</code>.

==== BC Smoothing Algorithm ====

The first control selects the BC smoothing algorithm. This setting is stored as <code>bc_filter</code>.

{| class="wikitable"
! Value !! Description
|-
| <code>median3</code> (default) || 3-sample median filter. Good default for rejecting isolated outliers.
|-
| <code>ema</code> || Exponential moving average. Smoother trend, slower response to abrupt changes.
|-
| <code>kalman</code> || Adaptive Kalman-style smoothing based on signal dynamics.
|}

==== Calibration (<code>dev:calibration</code>) ====

{| class="wikitable"
! Parameter !! Description !! Default
|-
| <code>sample_spot_diameter</code> || Sample spot diameter in cm. Used in BC mass concentration calculations. || 0.4
|-
| <code>filter_scattering_factor</code> || Filter scattering factor used by the optical correction model. || 1.39
|-
| <code>device_specific_correction_factor</code> || Per-device correction factor from lab comparison or provisioning. || 1.0
|}

==== Optical (<code>dev:optical</code>) ====

{| class="wikitable"
! Parameter !! Description !! Default
|-
| <code>burst_measurement</code> || LED is only enabled during the final seconds of a sample cycle. Experimental power/thermal mode. || false
|-
| <code>adc_block_samples</code> || ADC samples per sensor/reference block. Higher values reduce noise and increase capture time. || 256
|-
| <code>led_duty_cycle_370nm</code> || UV LED brightness/PWM duty for 370 nm channel. || 255
|-
| <code>led_duty_cycle_520nm</code> || Green LED brightness/PWM duty for 520 nm channel. || 255
|-
| <code>led_duty_cycle_880nm</code> || IR LED brightness/PWM duty for 880 nm channel. || 100
|-
| <code>cal_k_370nm</code> || Calibration factor for the 370 nm channel. || 1.0
|-
| <code>cal_k_520nm</code> || Calibration factor for the 520 nm channel. || 1.0
|-
| <code>cal_k_880nm</code> || Calibration factor for the 880 nm channel. || 1.0
|-
| <code>shadow_factor</code> || Weingartner shadow factor. Typical examples: 1.1 diesel, 1.2 urban, 1.5 biomass. || 1.2
|}

==== Pump (<code>dev:pump</code>) ====

{| class="wikitable"
! Parameter !! Description !! Default
|-
| <code>pump_dutycycle</code> || Base pump power/PWM duty. || 20
|-
| <code>max_pump_duty</code> || Maximum pump duty cycle. || 255
|-
| <code>min_pump_duty</code> || Minimum pump duty cycle. || 1
|-
| <code>min_airflow_ml</code> || Minimum airflow before stall recovery starts, in ml/min. || 70
|-
| <code>twelvevolt_duty</code> || 12V pump output duty cycle. || 20
|-
| <code>reverse_dutycycle</code> || Reverse pump duty-cycle handling for hardware variants. || false
|-
| <code>disable_pump_control</code> || Disable internal pump control loop. Use only with external control hardware. || false
|-
| <code>TWELVEVOLT_ENABLE</code> || Enable 12V power output. || false
|-
| <code>log_pump_duty</code> || Write pump duty cycle into the CSV per sample. || false
|}

==== Auto Flow Control (<code>dev:afc</code>) ====

{| class="wikitable"
! Parameter !! Description !! Default
|-
| <code>afc_bc_low</code> || BC concentration below which AFC moves toward maximum flow. || 300 ng/m³
|-
| <code>afc_bc_high</code> || BC concentration above which AFC moves toward minimum flow. || 2000 ng/m³
|-
| <code>afc_flow_low</code> || Minimum airflow when AFC is active. || 0.05 L/min
|-
| <code>afc_flow_high</code> || Maximum airflow when AFC is active. || 0.7 L/min
|-
| <code>afc_slope_gain</code> || Flow boost per 100 ng/min downward BC trend. || 0.05
|}

==== Hardware (<code>dev:hardware</code>) ====

{| class="wikitable"
! Parameter !! Description !! Default
|-
| <code>airflow_sensor</code> || Airflow sensor is installed and should be used. || true
|-
| <code>af_sensor_type</code> || Airflow sensor type: 0 = P0001A1, 1 = P0010A2. || 1
|-
| <code>enable_wifi</code> || WiFi connectivity is available. || true
|-
| <code>iot_enable</code> || 4G / IoT modem connectivity is available. || true
|-
| <code>show_undervoltage_warning</code> || Show warning when the optical 12V rail / ADC is not detected. || false
|}

==== System (<code>dev:system</code>) ====

{| class="wikitable"
! Parameter !! Description !! Default
|-
| <code>num_channels</code> || Number of optical wavelength channels. || 1
|-
| <code>is_ebcMeter</code> || Direct emission measurement mode. Changes units and emission-oriented behavior. || false
|-
| <code>device_name</code> || Device hostname/name used for mDNS and UI display. || bcMeter
|-
| <code>heating</code> || Enable heating hardware if installed. || false
|-
| <code>use_display</code> || Device has an attached display. || false
|-
| <code>email_service_password</code> || Mail service password for DIY/development devices. Provisioned devices normally already have this set. || email_service_password
|-
| <code>onboarding_step_one</code> || Phase 1 onboarding complete: contact email and WiFi setup. || false
|-
| <code>onboarding_step_two</code> || Phase 2 onboarding complete: calibration and data sharing choice. || false
|-
| <code>onboarding_email_sent</code> || Welcome/access email has already been sent. || false
|-
| <code>team_upload_interval</code> || Cloud/team upload interval in hours when data sharing is enabled. || 1
|-
| <code>bcmeter_team_email</code> || Contact email used for bcMeter team workflows. || empty
|-
| <code>last_cal_time</code> || Timestamp of the last successful calibration. || never
|}

=== Onboarding State ===

The current firmware stores onboarding progress with separate flags:

* <code>onboarding_step_one</code>: WiFi/email phase completed.
* <code>onboarding_step_two</code>: calibration/data-sharing phase completed.
* <code>onboarding_email_sent</code>: welcome email has already been sent.

The browser also uses local storage and cookies for temporary "Skip for now" behavior. "Don't show again" writes the matching onboarding step flag to the device.

=== Development Build Detection ===

When the device is running a development build, the status API returns <code>"env":"dev"</code>. The interface shows a red banner:

<blockquote style="background:#dc3545;color:#fff;padding:8px 16px;border-radius:4px;">DEVELOPMENT BUILD — connected to dev backend</blockquote>

=== 12V Power Warning ===

If the optical ADC is not detected, the interface can show a 12V warning:

<blockquote style="background:#fff3cd;padding:8px 16px;border-radius:4px;">'''⚠ 12V Power Missing''' — The optical ADC is not detected. Optics and light sensors will not function. Pump and airflow control may be limited by hardware state.</blockquote>

=== Platform Variants (DIY / open line vs assembled instruments) ===

The <code>bcmeter-dev</code> Raspberry Pi codebase powers '''bcMeter (DIY)''' builds, but it differs from the ESP32 firmware in the assembled instruments. Device-specific differences should be treated as implementation details of the same function:

* '''Networking:''' Raspberry Pi builds use FastAPI/uvicorn and NetworkManager, while ESP32 builds use the embedded web server and ESP-IDF WiFi stack.
* '''Optics/ADC:''' Pi builds use ADS8344E hardware (legacy units may use MCP342X); ESP32 builds use ADS1220-based optical acquisition.
* '''Firmware updates:''' bcMeter (DIY) builds may update through OS/GitHub release workflows, while ESP32 devices use OTA firmware images.
* '''Sensors:''' bcMeter (DIY) builds may expose DS18B20 or other prototype sensors that are not present on every ESP32 unit.

Best practices

2026-06-08T18:43:41Z

Bcmwiki: Consistency pass: multi-wavelength in-development, bcmeter-pi link, anchor/Flask/V2 fixes, airflow & ATN clarifications

== Best Practices ==

=== Environment ===

* Keep the device '''away from direct sunlight''', radiators, and fireplaces — it is sensitive to temperature and lighting changes.
* Position the inlet away from localized emission sources unless intentionally measuring them.
* For indoor use, avoid placement near HVAC vents or drafts.

=== Sampling Configuration ===

* '''Sample frequency:'''
** Ambient immission monitoring: '''180–600 seconds''' (3–10 min)
** Direct emissions from wood stoves (µg vs ng range): '''10–30 seconds'''
** Note: increasing frequency may increase noise.

* '''Airflow:'''
** Adjustable roughly between 25 and 500 mL/min (default 300 mL/min); the usable range narrows as the filter loads. With Auto Flow Control the device sets the rate automatically from the measured BC concentration.
** Higher airflow improves signal strength but loads the filter faster.

{| class="wikitable"
! Pollution Level !! Daily Avg BC !! Recommended Airflow
|-
| Heavy pollution || >2000 ng/m³ || 50 mL/min
|-
| Typical urban || ~500 ng/m³ || 100–250 mL/min
|-
| Low pollution || <500 ng/m³ || 300–400 mL/min
|}

When '''Auto Flow Control''' is enabled, the device adjusts airflow automatically based on measured BC concentration — reducing flow when BC is high (to extend filter life) and increasing flow when BC is low (for better signal).

=== Signal Quality ===

Signal-to-noise ratio improves with:
* Higher BC loads
* Higher air volume per sample
* Smaller sample spot diameter

'''Filtering:''' Apply median/average filtering (denoise slider) to reduce noise. The rolling average is closer to the "real" value than individual data points.

'''Calibration:''' Always calibrate after every filter change for reliable filter status indication and accurate measurement.

=== Filter Management ===

* At the default airflow in a typical urban environment (~500 ng/m³), a filter lasts approximately '''3–5 days'''.
* In heavily polluted areas, a filter may saturate in '''6–12 hours'''.
* Filter status is derived from attenuation (ATN): measurements are fully quantitative up to about ATN 75 and degrade at higher loading; the device flags the filter for replacement around ATN 120. (The ATN value is not a simple percentage of light loss.)
* The [[Configuration#Measurement Tab|Airflow Reference table]] in Settings helps estimate filter lifetime for your conditions.

=== Supported Filter Papers ===

{| class="wikitable"
! Filter Paper !! Scattering Correction Factor
|-
| Pall T60A20 || 1.0
|-
| AE33 Filter || 0.75
|-
| AE51 Filter || 1.0
|}

Other filter papers can be supported by determining their scattering factor. Send a sample to jd@bcmeter.org for calibration.

Troubleshooting

2026-06-08T18:43:41Z

Bcmwiki: Consistency pass: multi-wavelength in-development, bcmeter-pi link, anchor/Flask/V2 fixes, airflow & ATN clarifications

== Troubleshooting ==

{| class="wikitable"
! Issue !! Likely Cause & Solution
|-
| '''Negative data over a longer period''' || '''Temperature or lighting changes.''' Ensure the bcMeter is not in direct or reflected sunlight (keep reflections from windows on other side of the road in mind). Do not place near radiators or heat sources. If issue persists, contact support.
|-
| '''Device keeps restarting''' || '''Power supply.''' Cable too long or thin — see power requirements in [[Setup#Hardware Requirements|Setup]].
|-
| '''WiFi unstable or disconnects''' || Voltage instability (see power supply) or weak signal. The hotspot may temporarily disappear for 2–3 minutes during self-recovery — it returns automatically.
|-
| '''No WiFi networks listed''' || Reload the interface to re-initialize the network scan.
|-
| '''No data on graph''' || '''Sampling interval.''' The chart needs 3–4 samples before it can render. With the default 300s sample time, the first data point appears after ~15–20 minutes. Check that a session is running and wait for the first samples to arrive.
|-
| '''Pump noise when stopped''' || Motor controller signal latch. Go to '''Maintenance > Reboot Device''' or start a new log and stop right after initialization.
|-
| '''Pump stall / no airflow''' || The device has automatic stall protection. If flow drops below threshold for 3 seconds, recovery is attempted (up to 4 times). After 4 failures, measurement stops with pump error. Check for blocked tubing, saturated filter, or hardware issues.
|-
| '''"Time: not synced" warning''' || Device clock not synchronized. Internet-connected devices sync automatically; for offline devices, use Maintenance > Time Synchronization.
|-
| '''Email notifications not working''' || Verify the email service password (API key) is entered and validated in Email settings. Check that at least one valid recipient address is configured.
|-
| '''Sensor values very low, don't change''' || Check voltages on LED and sensor connections. Verify 12V power is connected (the optical ADC requires it). Run calibration with a clean filter.
|-
| '''ADC saturation error''' || LED too bright or sensor oversaturated. The device attempts auto-recovery by reducing LED duty. If persistent, recalibrate with a fresh filter. Check in [[Developer mode]] if advanced LED settings need adjustment.
|-
| '''Overtemperature warning''' || Internal temperature exceeded 65°C. Move the device to a cooler location. Measurement pauses automatically and resumes when temperature drops.
|}

=== Error Codes ===

These numerical error codes are '''not''' shown in the frontend interface. They appear in the [[API reference|Status API]] response (<code>/api/status</code> → <code>error</code> and <code>error_msg</code> fields) and in the '''System Logs''' (accessible from Maintenance). The interface displays a human-readable error message instead.

{| class="wikitable"
! Code !! Name !! Description
|-
| 0 || ERR_NONE || No error
|-
| 1 || ERR_ADC_LOW || Sensor reading too low — filter extremely loaded
|-
| 2 || ERR_ADC_SATURATED || Sensor reading saturated — LED too bright; at low duty this indicates no filter is present
|-
| 3 || ERR_FLOW_ZERO || Pump stall, airflow below minimum
|-
| 4 || ERR_OVERTEMP || Temperature >65°C
|-
| 5 || ERR_LED_FAILURE || LED not functioning
|-
| 6 || ERR_ATN_LIMIT || Attenuation >120 — filter extremely clogged
|-
| 7 || ERR_OUTLIER_EXCESS || >80% of readings out-of-bounds
|}

=== Getting Help ===

If your issue isn't listed here, contact jd@bcmeter.org with:
* Description of the problem
* Screenshot of the interface
* System logs (download from '''Maintenance > Download Logs''')

Main Page

2026-06-08T18:43:41Z

Bcmwiki: Consistency pass: multi-wavelength in-development, bcmeter-pi link, anchor/Flask/V2 fixes, airflow & ATN clarifications

== Welcome to the [https://bcmeter.org bcmeter.org] Wiki ==

The bcMeter wiki is the technical documentation hub for the bcMeter platform — an optical absorption photometer for measuring Black Carbon (BC) aerosols in real-time. The platform spans the source-available '''bcMeter (DIY)''' (build it yourself) and the ready-to-use '''bcMeter Kit, bcMeter Complete and eBcMeter''' instruments.

Whether you are setting up a new device, configuring measurements, or building your own unit, this wiki covers everything you need.

== Getting Started ==

* [[Introduction]] — What is bcMeter, how it works, capabilities
* [[Setup]] — Hardware requirements, first boot, WiFi configuration
* [[Interface]] — Web dashboard overview, status indicators, chart controls

== Using bcMeter ==

* [[Configuration]] — All settings: network, measurement, device, email
* [[Maintenance]] — Filter changes, calibration, data management
* [[Troubleshooting]] — Common issues and solutions
* [[Best practices]] — Environment, sampling, signal quality

== Technical Reference ==

* [[Developer mode]] — Hidden developer settings, hardware tuning
* [[API reference]] — REST API endpoints for automation and integration
* [[CSV data format]] — Column definitions and data structure
* [[Serial commands]] — USB debug interface

== bcMeter (DIY) — build it yourself ==

''These pages document the source-available bcMeter (DIY) — the Raspberry-Pi-based design, freely available for private, educational and research use (CC BY-NC 4.0), built from open design files (nothing is sold). The assembled bcMeter Kit, Complete and eBcMeter use a different hardware design.''

* [[Working principle]] — Optical measurement principle
* [[Bill of material]] — Component list and costs (bcMeter DIY)
* [[Device assembly]] — Hardware build instructions (bcMeter DIY)

== Software ==

The bcMeter software is source-available — freely available for private, educational and research use (CC BY-NC 4.0): '''[https://github.com/dahljo/bcmeter-pi github.com/dahljo/bcmeter-pi]'''

The codebase includes the web [[Interface|interface]], [[API reference|REST API]], measurement engine, and all device management functionality.

== Contact ==

* '''Technical inquiries & devices:''' Jonas Dahl — jd@bcmeter.org
* '''Black carbon science & air quality:''' Axel Friedrich — af@bcmeter.org
* '''Project website:''' [https://bcmeter.org bcmeter.org]

Introduction

2026-06-08T18:43:41Z

Bcmwiki: Consistency pass: multi-wavelength in-development, bcmeter-pi link, anchor/Flask/V2 fixes, airflow & ATN clarifications

== Introduction ==

The '''bcMeter''' is a source-available optical absorption photometer designed to measure Black Carbon (BC) aerosols — commonly known as soot — in real-time. The design is freely available for private, educational and research use (CC BY-NC 4.0); assembled instruments are offered on request. Whether you are monitoring ambient air quality in your neighborhood or measuring direct emissions from wood stoves, this device provides scientific-grade data at a fraction of the cost of reference instruments.

The device operates "headless" — it has no built-in screen. Instead, it hosts its own website that you can access from any smartphone or computer connected to the same network.

The software is source-available — freely available for private, educational and research use (CC BY-NC 4.0): [https://github.com/dahljo/bcmeter-pi github.com/dahljo/bcmeter-pi]

=== Device Types ===

* '''bcMeter (DIY)''' — The source-available, self-build version. Runs on a Raspberry Pi using the open PCB design, freely available for private, educational and research use (CC BY-NC 4.0). Build your own from the open design files and the Wiki (nothing is sold).
* '''bcMeter Kit''' — Assembled-instrument PCB plus components for self-assembly and 3D printing. Available on request.
* '''bcMeter Complete''' — Fully assembled, ready-to-use instrument on a compact platform that starts in seconds and updates over the air, with no microSD card or Linux system to maintain. Available on request.
* '''eBcMeter''' — Emission measurement instrument for direct source sampling from wood-burning stoves and similar combustion sources. Uses microgram (µg) units instead of nanogram (ng). Available on request.

=== How Does It Work? ===

[[File:Working principle of a bcMeter.png|300px|right]]

# Polluted air is drawn through filter paper by a pump
# The filter paper absorbs black carbon (BC) particles
# An LED shining at 880 nm passes through the filter; a sensor measures the attenuation (reduction in light intensity)
# A separate reference channel monitors the same LED through a clean portion of the filter, compensating for environmental changes
# The attenuation is converted to BC concentration (ng/m³) using Beer-Lambert law
# Data is saved as CSV and displayed in real-time on the web interface

'''Multi-wavelength (in development):''' Additional 520 nm and 370 nm channels for source apportionment via the Ångström Exponent (AAE) are in development and '''not available in shipped hardware'''. Current devices measure at 880 nm only.

=== Sensors & Capabilities ===

==== Core ====

{| class="wikitable"
! Measurement !! Sensor / Method !! Notes
|-
| Black Carbon (BC) || Optical absorption at 880 nm || Primary measurement
|-
| Temperature / Humidity || SHT4x ||
|-
| Airflow || Omron D6F differential pressure || Pump flow rate
|}

==== Optional Hardware ====

{| class="wikitable"
! Measurement !! Sensor / Method !! Notes
|-
| Temperature / Humidity / Pressure || BME280 || Barometric altitude
|-
| PM2.5 / PM10 || Sensirion SPS30 || Particulate matter
|-
| GPS || AT6668 UART || Position, altitude, speed
|-
| 4G Connectivity || SIM7080G LTE-M modem || Remote data upload
|}

CSV data format

2026-06-08T16:20:51Z

Bcmwiki: Fix ATN formula: ATN = -100*ln(Sen/Ref), dimensionless; sigma enters BC not ATN (verified vs firmware measure.cpp)

== CSV Data Format ==

bcMeter stores measurement data as CSV files. This page documents the file format and column definitions.

=== File Format ===

{| class="wikitable"
! Property !! Value
|-
| Delimiter || Semicolon (<code>;</code>)
|-
| Encoding || UTF-8
|-
| Decimal separator || Dot (<code>.</code>)
|-
| Line ending || LF (<code>\n</code>)
|-
| First row || Column headers
|}

=== Filename Convention ===

* Active session: <code>YY-MM-DD_HHMMSS.csv</code> (based on session start time)
* Fallback (no RTC sync): <code>nosync_HHMMSS.csv</code> (based on uptime)

=== Column Definitions ===

==== Core Columns (always present) ====

{| class="wikitable"
! Column !! Type !! Unit !! Description
|-
| <code>bcmDate</code> || string || DD-MM-YY || Measurement date
|-
| <code>bcmTime</code> || string || HH:MM:SS || Measurement time
|-
| <code>bcmRef_880nm</code> || float || V || Reference channel voltage (880nm LED through clean filter)
|-
| <code>bcmSen_880nm</code> || float || V || Sensor channel voltage (880nm LED through sample spot)
|-
| <code>bcmATN_880nm</code> || float || — || Attenuation at 880nm = −100·ln(Sen/Ref), dimensionless. The absorption cross-section σ enters the BC concentration, not ATN.
|-
| <code>BCngm3_unfiltered_880nm</code> || float || ng/m³ || Real-time BC concentration (unsmoothed)
|-
| <code>BCngm3_880nm</code> || float || ng/m³ || BC concentration with rolling average applied
|-
| <code>relativeLoad</code> || float || % || Filter loading (0 = clean, 100 = saturated)
|-
| <code>AAE</code> || float || — || Ångström Absorption Exponent (requires multi-wavelength)
|-
| <code>Temperature</code> || float || °C || Internal device temperature
|-
| <code>airflow</code> || float || L/min || Measured airflow rate
|}

==== Multi-Wavelength Columns (optional, if hardware installed) ====

Same structure as 880nm, repeated for each wavelength:

* <code>bcmRef_520nm</code>, <code>bcmSen_520nm</code>, <code>bcmATN_520nm</code>, <code>BCngm3_unfiltered_520nm</code>, <code>BCngm3_520nm</code>
* <code>bcmRef_370nm</code>, <code>bcmSen_370nm</code>, <code>bcmATN_370nm</code>, <code>BCngm3_unfiltered_370nm</code>, <code>BCngm3_370nm</code>

==== Environmental Columns (optional, sensor-dependent) ====

{| class="wikitable"
! Column !! Type !! Unit !! Description
|-
| <code>humidity</code> || float || % || Relative humidity (BME280/SHT4x)
|-
| <code>hPa</code> || float || hPa || Atmospheric pressure (BME280)
|-
| <code>PM2.5</code> || float || µg/m³ || Particulate matter <2.5µm (SPS30)
|-
| <code>PM10</code> || float || µg/m³ || Particulate matter <10µm (SPS30)
|}

==== GPS Columns (optional, if GPS module connected and has fix) ====

{| class="wikitable"
! Column !! Type !! Unit !! Description
|-
| <code>lat</code> || float || degrees || Latitude (WGS84)
|-
| <code>lon</code> || float || degrees || Longitude (WGS84)
|-
| <code>altitude</code> || float || m || GPS altitude above sea level
|}

==== Metadata Columns ====

{| class="wikitable"
! Column !! Type !! Description
|-
| <code>notice</code> || string || System notices or warnings per data point
|-
| <code>sampleDuration</code> || float || Actual measurement duration for this sample (seconds)
|-
| <code>notes</code> || string || User-added annotations
|}

=== Example Data ===

<pre>
bcmDate;bcmTime;bcmRef_880nm;bcmSen_880nm;bcmATN_880nm;BCngm3_unfiltered_880nm;BCngm3_880nm;relativeLoad;AAE;Temperature;airflow
04-03-26;19:37:09;0.9679;0.9321;3.76;1686;1686;0;0;0;0.4659
04-03-26;19:42:09;0.9745;0.9335;4.3;4028.5;1686;0;0;0;0.3088
04-03-26;19:47:09;0.9752;0.9315;4.59;2371.4;1830.2;0;0;0;0.2832
</pre>

=== Import Notes ===

* '''Excel:''' Use "Text Import Wizard" and set delimiter to semicolon. The date format DD-MM-YY may need manual conversion.
* '''Python/Pandas:''' <code>pd.read_csv('file.csv', sep=';')</code>
* '''R:''' <code>read.csv2('file.csv')</code> (uses semicolon by default)

Setup

2026-06-08T10:35:07Z

Bcmwiki: Reframe: bcMeter (DIY) / source-available

== Setup & Initialization ==

=== Hardware Requirements ===

'''Use a stable power supply:''' Weak adapters and voltage drops are the most common causes of WiFi dropouts and random reboots.

* bcMeter Kit/Complete: use a suitable '''12V / 2A''' power adapter.
* bcMeter (DIY): use a suitable '''5V / 2.5A''' power adapter.
* Use a '''short, low-resistance cable''' (ideally under 40 cm). Long or thin cables can drop enough voltage to reboot the device when the pump starts.

=== Initial Device Setup ===

Before starting measurements:

# Place the device '''away from direct heat sources and sunlight''' (thermal drift affects optical measurements).
# Insert a fresh filter paper ('''marked side facing up''' — see [[Maintenance#Filter Change Procedure|Filter Change Procedure]]).
# If using a rugged case: check that the hose from bcMeter to the outside air is firmly inserted and not blocked.

=== Connecting via Hotspot ===

The device creates its own WiFi network automatically on first boot, or when no known network is available. It can also be forced via Settings (Hotspot Mode).

# Plug in the device.
# Wait '''1-2 minutes''' for the system to boot.
# On your phone or computer, search for a WiFi network whose name starts with '''bcMeter''' or '''eBcMeter'''.
# If asked, connect using the password <code>bcMeterbcMeter</code> (case sensitive). Current assembled bcMeter instruments may create an open setup hotspot and will not ask for a password.
# Your phone may warn "No Internet Connection." '''This is normal.''' Select "Keep Connected" if prompted. Do not choose "use mobile data."
# Open a browser and type <code><nowiki>http://bcmeter-XXXX.local</nowiki></code> (where XXXX are the last 4 hex characters of the MAC address, e.g. <code>bcmeter-A3AB</code>) or <code><nowiki>http://192.168.18.8</nowiki></code>.

The '''[[Setup#Welcome Screen|Welcome Screen]]''' will appear on first use.

'''Apple users:''' If already connected to another WiFi, the bcMeter hotspot will appear under "Other Networks" submenu. macOS may take up to a minute to scan for new networks.

=== Welcome Screen ===

On first use, bcMeter shows a two-phase welcome screen for network setup, calibration, and data sharing.

==== Phase 1: Connect ====

The first screen ("Connect this bcMeter") covers connectivity:

* '''Notification email''' — Enter the address where bcMeter should send status messages and alerts. After WiFi setup, the device can send its URL and connection details to this address.
* '''Enable email notifications''' — Toggle to receive status updates and measurement reports.
* '''Connect to network''' — Select your network from the dropdown, click '''Scan''' to refresh, or choose '''Enter manually''' for hidden networks. Enter the WiFi password and click '''Connect'''.

The email step offers "Skip for now" and "Don't show again". The WiFi step offers "Back" and "Skip".

==== Phase 2: Calibrate & Share ====

After connecting to WiFi (or if WiFi was already configured), the second screen ("Almost there") appears:

* '''Install a clean filter''' — Place a fresh quartz filter in the holder.
* '''Calibrate''' — Perform a baseline reading. Click "Start calibration →" to open the calibration dialog directly.
* '''Data sharing''' — Shared measurements help build the bcMeter black carbon map. You can choose:
** '''Get Started & Share Data''' — Enables anonymous data sharing for the project.
** '''Get Started without Sharing''' — Proceeds without sharing. You can change this later in Settings.

The calibration/sharing phase has "Skip for now" and "Don't show again" options at the bottom.

'''Tip:''' The welcome screen will reappear on each visit until setup is complete or you choose "Don't show again."

'''Important:''' Run [[Maintenance#Calibration|calibration]] after setup.

=== Connecting to Wireless Network ===

If you skipped WiFi setup on the welcome screen, or need to change your network later:

# Navigate to '''Settings''' > '''Network''' tab.
# Select your network from the list. For hidden networks, choose "Enter manually" and type the SSID yourself.
# Enter your WiFi key and click '''Connect'''.
# The setup hotspot disconnects while the device joins the selected network. Reconnect your computer to your normal WiFi.
# Wait 1–2 minutes for the device to join your network.

Click "Forget Network" in the Network tab to disconnect from the stored network and force the device to create its hotspot again.

=== Accessing the Interface ===

When the device is on your network, open it by hostname. The default hostname follows the pattern <code>bcmeter-XXXX</code> (or <code>ebcmeter-XXXX</code> for emission devices), where XXXX are the last 4 hex characters of the device's MAC address. For example:

* Standard device: <code><nowiki>http://bcmeter-A3AB.local</nowiki></code>
* Emission control version: <code><nowiki>http://ebcmeter-A3AB.local</nowiki></code>

The exact hostname is shown on the device label and in the Welcome screen email. You can rename the device in Settings > Device > Device Name.

'''Tip:''' If <code>.local</code> addresses do not work (common on some Windows networks or older routers), find the device's IP address in your router's administration interface.

'''Browser Security Warnings:''' The bcMeter web server uses HTTP (not HTTPS), which triggers browser warnings. This is expected — the device runs locally on your network with no public internet connection. You must explicitly allow access to the device's <code>.local</code> address. On macOS, you may also need to grant permission for your browser to access LAN devices.

=== Connection Lost ===

If the browser loses contact with the device (for example during a reboot or network drop), a "Connection Lost" overlay appears. The interface keeps trying to reconnect until the device is reachable again.

Installation

2026-06-08T10:35:06Z

Bcmwiki: Reframe: bcMeter (DIY) / source-available

{{Note|1='''bcMeter (DIY)''' — This page documents software setup for the source-available bcMeter (DIY) — the Raspberry-Pi-based design, freely available for private, educational and research use (CC BY-NC 4.0). The assembled bcMeter instruments come pre-configured and are set up via the [[Setup#Welcome Screen|Welcome Screen]].}}

== Recommended: Pre-configured microSD Card Image (bcMeter DIY) ==

=== Step 1: Download and Flash the Image ===

# Download the bcMeter image file [https://bcmeter.org/wp-content/uploads/simple-file-list/bcMeter_latest_img.zip here]
# Unzip the downloaded file
# Use [https://www.balena.io/etcher/ Etcher] to flash the image to your microSD card:
#* Insert your microSD card
#* Open Etcher and select the image
#* Select your microSD card as target
#* Click "Flash!" and wait for completion

=== Step 2: Boot and Connect ===

# Insert the flashed microSD card into the Raspberry Pi
# Power on the device
# Wait approximately 2 minutes for boot
# Connect to the WiFi network "'''bcMeter'''" with password: <code>bcMeterbcMeter</code>

=== Step 3: Configure ===

# Open a browser and navigate to <code><nowiki>http://bcmeter-XXXX.local</nowiki></code> (where XXXX are the last 4 hex characters of the MAC address, shown on the device label)
# The bcMeter interface will appear
# Follow on-screen instructions

== Advanced: Manual Setup via SSH (bcMeter DIY) ==

Use the [https://www.raspberrypi.com/software/ Raspberry Pi Imager] to write '''Raspberry OS 64-bit LITE''' to the microSD card. Do '''not''' install the Desktop variant.

Configure with username <code>bcmeter</code> and password <code>bcmeter.org</code>. Enable SSH and WiFi.

=== SSH Installation ===

<pre>
ssh bcmeter@bcMeter
# or: ssh bcmeter@bcMeter.local

# Download and run installer
wget -N https://raw.githubusercontent.com/bcmeter/bcmeter/main/install.sh && sudo bash install.sh
</pre>

This runs an unattended installation taking a few minutes.

== Assembled instruments (Kit/Complete/eBcMeter) ==

The assembled bcMeter instruments come with firmware pre-installed. Setup only requires:

# Plug in power
# Connect to the "bcMeter" WiFi hotspot
# Open <code><nowiki>http://bcmeter-XXXX.local</nowiki></code> (XXXX = last 4 hex chars of MAC address)
# Follow the [[Setup#Welcome Screen|Welcome Screen]]

See [[Setup]] for detailed instructions.

Device assembly

2026-06-08T10:35:05Z

Bcmwiki: Reframe: bcMeter (DIY) / source-available

{{Note|1='''bcMeter (DIY)''' — This page documents assembly of the source-available bcMeter (DIY) — the Raspberry-Pi-based design, freely available for private, educational and research use (CC BY-NC 4.0). The assembled bcMeter instruments use a different hardware design.}}

'''bcMeter (DIY) Assembly Documentation''' (v02, January 2025)

== LED and Sensor Brackets ==

The orientation of both the 3D printed infrared LED and sensor assemblies has been simplified to reduce orientation mismatches.

The infrared LEDs are housed in clear-looking parts while the infrared sensors are in dark parts. Each must be correctly oriented – note that the spherical lens on each part should point toward the shorter end of the bracket, ensuring both point toward the filter paper.

* '''Glueing:''' Use plastics glue (avoid "super glue" as it can leave residue that affects LED and phototransistor sensitivity for days or weeks). Place a droplet of glue on each leg to close the hole.

* '''Assembly:'''
** Insert the LED and sensor bracket assembly into the case.
** Pre-treat both counterparts with plastics glue before insertion to create airtight channels.
** Ensure the middle section between the sample and sensor areas is completely covered with glue to prevent air leakage.
* '''Fixing:''' Prior to insertion, secure the LEDs and sensors with plastic or hot glue (avoid tilting; check orientation).
* '''Mounting:''' Once inserted, mount the brackets to the case and verify that the LED and sensor lenses are centered.

== Reference & Sample Parts ==

On the circuit board, the LEDs must be connected in series. The negative pin of the first LED serves as the positive pin for the second LED. Use a standard 4-pin 2.54 mm JST connector and cable, soldering the connections in the order:

: '''red – black – yellow – white''' - connect one by one. If your cable has different coloring, maintain the same electrical order.

The infrared sensors (for measuring attenuation) are connected '''in parallel'''. Their connections follow a different order:

: '''black – red – white – yellow'''

This completes the most crucial part of the bcMeter assembly. LED-to-sensor orientation and air leakage directly affect accuracy. Minor misalignments can be compensated by the [[Maintenance#Calibration|Calibration function]].

== Sealing ==

Continue case assembly by adding a rubber seal to the bottom part:

* Ensure the seal's diameter is precisely known — critical for accuracy.
* Check for air leakage; if needed, apply a second seal to the top part and ensure holes overlap.
* To verify diameter, let the paper run black and examine the sample spot.
* Add M3 screw threads to the poles and use superglue to secure them.

== Pump Control Circuit ==

The bcMeter is versatile with pump selection. Any pump running at 5V will work. Two low-cost types:

* '''Membrane pumps''' — Recommended.
* '''Propeller pumps''' — Not recommended for this use case.

Membrane pumps can use a PWM controller (Type A) or operate without one (Type B). For PWM-controlled pumps, remove Q4 from the PCB.

== Airflow Meter Setup ==

If an airflow meter is used:

* Connect the pump's input to the airflow sensor's output.
* Connect the airflow sensor's input to the air sampling connector.
* Connect the pump's output to the bcMeter's air output.

== Finalizing the Build ==

* Insert filter paper and screw the top part of the case by hand.
* Connect a stronger 12V pump and cover the air inlet.
* If noise is heard (indicating leakage), use glue to seal the gap.

== Description of the Components (bcMeter DIY) ==

* '''U1:''' MCP3428 4-Channel Analogue/Digital Converter
* '''D1 / D2:''' IR LED connector for sensor and reference
* '''Q1 / Q2:''' IR Phototransistor for sensor and reference (ADC Channels 1 and 2)
* '''J1:''' Omron D6F Airflow Sensor (ADC Channel 4)
* '''J2:''' SSD1306 Display (optional)
* '''J7:''' Heater or Fan (optional)
* '''J12:''' SPI Header (optional)
* '''J5:''' Air Pump
* '''J4 / J9:''' PWM + Power for Air Pump (remove Q4 for PWM pump)
* '''Additional:''' Several headers (I2C, ADC, Power) for expandability

Bill of material

2026-06-08T10:35:04Z

Bcmwiki: Reframe: bcMeter (DIY) / source-available

{{Note|1='''bcMeter (DIY)''' — This page documents the bill of materials for the source-available bcMeter (DIY) — the Raspberry-Pi-based design, freely available for private, educational and research use (CC BY-NC 4.0). The assembled bcMeter instruments use a different PCB design.}}

== Overview of Parts (bcMeter DIY) ==

[[File:bcMeter_parts.jpg|thumb|none|800px]]

== Mandatory Components ==

# '''bcMeter Pi Hat''' — Order prepopulated (~95 EUR) or build your own from PCB + components (~5 EUR per PCB for 10+ on JLCPCB or similar)
# '''Raspberry Pi 3A or Zero 2 W''' (~35 EUR)
# '''MicroSD Card''' (~10 EUR)
# '''Power Supply 5.25V/2A''' (~15 EUR)
# '''Air Pump''' (~10–200 EUR depending on type)

''Prefer not to source parts? bcMeter Kit/Complete available on request — contact jd@bcmeter.org.''

== 3D Printed Case ==

STL files for 3D Printing (SLA or FDM): [https://github.com/bcmeter/bcmeter/tree/main/stl GitHub repository] — printing material ~10 EUR.

Use black filament/resin. FDM is prone to leakage if not properly configured. If possible, mix resin with flex resin.

== Filter Paper ==

AE33 filter paper is standard for bcMeter. Any filter paper with a known scattering factor can be used. See [[Best practices#Supported Filter Papers|Supported Filter Papers]] for correction factors.

Send a sample of your filter paper to jd@bcmeter.org for calibration.

== Additional Material (~75 EUR) ==

{| class="wikitable"
! Description !! Quantity !! Approx. Price
|-
| 22 AWG Wire || 1 || $10
|-
| Hot Glue || 1 || $7
|-
| Rubber Band (SHORE A) for sealing || 1 || $13
|-
| Silicone Hose (5mm ID) || 1 || $5
|-
| M3 Screws || 1 set || $7
|-
| M3 Threaded Inserts || 1 set || $7
|-
| MicroSD Card 16GB || 1 || $8
|}

== Key PCB Components ==

{| class="wikitable"
! Component !! Description !! Approx. Price
|-
| '''U1''' MCP3428 || 4-Channel ADC || €6
|-
| '''D1/D2''' IRL81A || IR LEDs (880nm) || €2
|-
| '''J1''' Omron D6F || Airflow Sensor || €50
|-
| '''U2''' LM1117 || Voltage Regulator || €1
|-
| '''U3''' SHT4x || Humidity/Temp Sensor || €4
|-
| '''Pump''' D15S PWM || Membrane Pump || €95
|-
| Capacitors, resistors, connectors || Various || ~€20
|}

Full BOM with exact product numbers available at [https://github.com/bcmeter/bcmeter GitHub].

== PCB / Gerber Files ==

Gerber files for PCB fabrication: [https://github.com/bcmeter/bcmeter/tree/main/gerbers GitHub]

Two PCB variants exist:
* '''SMD PCB''' — For 5V and smaller pumps. More compact, recommended.
* '''THT PCB''' — For 12V and larger pumps. Easier to assemble but less accurate.

== Assembled instruments (Kit/Complete/eBcMeter) ==

The assembled bcMeter instruments use a different hardware design:

* '''ADS1220''' 24-bit ADC (replaces MCP3428)
* '''Integrated microcontroller''' (instead of the Raspberry Pi used in the DIY build)
* '''Internal flash storage''' (replaces microSD)
* '''Optional:''' SIM7080G LTE-M modem, AT6668 GPS, SPS30 PM sensor

For current device information, see [[Introduction]].

Developer mode

2026-06-08T10:35:03Z

Bcmwiki: Reframe: bcMeter (DIY) / source-available

== Developer Mode ==

The bcMeter interface has a hidden developer mode for hardware tuning and diagnostics. '''Changes in developer mode affect hardware directly''' and can make measurements unusable when set incorrectly. Use it only for support, development, or device-specific provisioning.

=== Activating Developer Mode ===

# Open '''Settings'''.
# Click the '''device name''' text next to "Configuration" '''7 times within 3 seconds'''.
# The name changes to include <code>[DEV]</code>.
# A new '''⚠ Dev''' tab appears in the settings panel.

Developer mode is active for the current page session and is reset when the page is reloaded.

=== Developer Tab Layout ===

The Developer tab opens with a warning banner:

<blockquote style="background:#fff3cd;padding:8px 16px;border-radius:4px;">Developer mode — changes affect hardware directly. Save only if you know what you are doing.</blockquote>

Settings are grouped by namespace. The values below match the current ESP32 firmware defaults in <code>cfgstore.cpp</code>.

==== BC Smoothing Algorithm ====

The first control selects the BC smoothing algorithm. This setting is stored as <code>bc_filter</code>.

{| class="wikitable"
! Value !! Description
|-
| <code>median3</code> (default) || 3-sample median filter. Good default for rejecting isolated outliers.
|-
| <code>ema</code> || Exponential moving average. Smoother trend, slower response to abrupt changes.
|-
| <code>kalman</code> || Adaptive Kalman-style smoothing based on signal dynamics.
|}

==== Calibration (<code>dev:calibration</code>) ====

{| class="wikitable"
! Parameter !! Description !! Default
|-
| <code>sample_spot_diameter</code> || Sample spot diameter in cm. Used in BC mass concentration calculations. || 0.4
|-
| <code>filter_scattering_factor</code> || Filter scattering factor used by the optical correction model. || 1.39
|-
| <code>device_specific_correction_factor</code> || Per-device correction factor from lab comparison or provisioning. || 1.0
|}

==== Optical (<code>dev:optical</code>) ====

{| class="wikitable"
! Parameter !! Description !! Default
|-
| <code>burst_measurement</code> || LED is only enabled during the final seconds of a sample cycle. Experimental power/thermal mode. || false
|-
| <code>adc_block_samples</code> || ADC samples per sensor/reference block. Higher values reduce noise and increase capture time. || 256
|-
| <code>led_duty_cycle_370nm</code> || UV LED brightness/PWM duty for 370 nm channel. || 255
|-
| <code>led_duty_cycle_520nm</code> || Green LED brightness/PWM duty for 520 nm channel. || 255
|-
| <code>led_duty_cycle_880nm</code> || IR LED brightness/PWM duty for 880 nm channel. || 100
|-
| <code>cal_k_370nm</code> || Calibration factor for the 370 nm channel. || 1.0
|-
| <code>cal_k_520nm</code> || Calibration factor for the 520 nm channel. || 1.0
|-
| <code>cal_k_880nm</code> || Calibration factor for the 880 nm channel. || 1.0
|-
| <code>shadow_factor</code> || Weingartner shadow factor. Typical examples: 1.1 diesel, 1.2 urban, 1.5 biomass. || 1.2
|}

==== Pump (<code>dev:pump</code>) ====

{| class="wikitable"
! Parameter !! Description !! Default
|-
| <code>pump_dutycycle</code> || Base pump power/PWM duty. || 20
|-
| <code>max_pump_duty</code> || Maximum pump duty cycle. || 255
|-
| <code>min_pump_duty</code> || Minimum pump duty cycle. || 1
|-
| <code>min_airflow_ml</code> || Minimum airflow before stall recovery starts, in ml/min. || 70
|-
| <code>twelvevolt_duty</code> || 12V pump output duty cycle. || 20
|-
| <code>reverse_dutycycle</code> || Reverse pump duty-cycle handling for hardware variants. || false
|-
| <code>disable_pump_control</code> || Disable internal pump control loop. Use only with external control hardware. || false
|-
| <code>TWELVEVOLT_ENABLE</code> || Enable 12V power output. || false
|-
| <code>log_pump_duty</code> || Write pump duty cycle into the CSV per sample. || false
|}

==== Auto Flow Control (<code>dev:afc</code>) ====

{| class="wikitable"
! Parameter !! Description !! Default
|-
| <code>afc_bc_low</code> || BC concentration below which AFC moves toward maximum flow. || 300 ng/m³
|-
| <code>afc_bc_high</code> || BC concentration above which AFC moves toward minimum flow. || 2000 ng/m³
|-
| <code>afc_flow_low</code> || Minimum airflow when AFC is active. || 0.05 L/min
|-
| <code>afc_flow_high</code> || Maximum airflow when AFC is active. || 0.7 L/min
|-
| <code>afc_slope_gain</code> || Flow boost per 100 ng/min downward BC trend. || 0.05
|}

==== Hardware (<code>dev:hardware</code>) ====

{| class="wikitable"
! Parameter !! Description !! Default
|-
| <code>airflow_sensor</code> || Airflow sensor is installed and should be used. || true
|-
| <code>af_sensor_type</code> || Airflow sensor type: 0 = P0001A1, 1 = P0010A2. || 1
|-
| <code>enable_wifi</code> || WiFi connectivity is available. || true
|-
| <code>iot_enable</code> || 4G / IoT modem connectivity is available. || true
|-
| <code>show_undervoltage_warning</code> || Show warning when the optical 12V rail / ADC is not detected. || false
|}

==== System (<code>dev:system</code>) ====

{| class="wikitable"
! Parameter !! Description !! Default
|-
| <code>num_channels</code> || Number of optical wavelength channels. || 1
|-
| <code>is_ebcMeter</code> || Direct emission measurement mode. Changes units and emission-oriented behavior. || false
|-
| <code>device_name</code> || Device hostname/name used for mDNS and UI display. || bcMeter
|-
| <code>heating</code> || Enable heating hardware if installed. || false
|-
| <code>use_display</code> || Device has an attached display. || false
|-
| <code>email_service_password</code> || Mail service password for DIY/development devices. Provisioned devices normally already have this set. || email_service_password
|-
| <code>onboarding_step_one</code> || Phase 1 onboarding complete: contact email and WiFi setup. || false
|-
| <code>onboarding_step_two</code> || Phase 2 onboarding complete: calibration and data sharing choice. || false
|-
| <code>onboarding_email_sent</code> || Welcome/access email has already been sent. || false
|-
| <code>team_upload_interval</code> || Cloud/team upload interval in hours when data sharing is enabled. || 1
|-
| <code>bcmeter_team_email</code> || Contact email used for bcMeter team workflows. || empty
|-
| <code>last_cal_time</code> || Timestamp of the last successful calibration. || never
|}

=== Onboarding State ===

The current firmware stores onboarding progress with separate flags:

* <code>onboarding_step_one</code>: WiFi/email phase completed.
* <code>onboarding_step_two</code>: calibration/data-sharing phase completed.
* <code>onboarding_email_sent</code>: welcome email has already been sent.

The browser also uses local storage and cookies for temporary "Skip for now" behavior. "Don't show again" writes the matching onboarding step flag to the device.

=== Development Build Detection ===

When the device is running a development build, the status API returns <code>"env":"dev"</code>. The interface shows a red banner:

<blockquote style="background:#dc3545;color:#fff;padding:8px 16px;border-radius:4px;">DEVELOPMENT BUILD — connected to dev backend</blockquote>

=== 12V Power Warning ===

If the optical ADC is not detected, the interface can show a 12V warning:

<blockquote style="background:#fff3cd;padding:8px 16px;border-radius:4px;">'''⚠ 12V Power Missing''' — The optical ADC is not detected. Optics and light sensors will not function. Pump and airflow control may be limited by hardware state.</blockquote>

=== Platform Variants (DIY / open line vs assembled instruments) ===

The <code>bcmeter-dev</code> Raspberry Pi codebase powers '''bcMeter (DIY)''' builds, but it differs from the ESP32 firmware in the assembled instruments. Device-specific differences should be treated as implementation details of the same function:

* '''Networking:''' Raspberry Pi builds may use Flask and NetworkManager, while ESP32 builds use the embedded web server and ESP-IDF WiFi stack.
* '''Optics/ADC:''' Pi builds may reference ADS8344E or MCP342X hardware; current ESP32 V2 builds use ADS1220-based optical acquisition.
* '''Firmware updates:''' bcMeter (DIY) builds may update through OS/GitHub release workflows, while ESP32 devices use OTA firmware images.
* '''Sensors:''' bcMeter (DIY) builds may expose DS18B20 or other prototype sensors that are not present on every ESP32 unit.

API reference

2026-06-08T10:35:02Z

Bcmwiki: Reframe: bcMeter (DIY) / source-available

== API Reference ==

The bcMeter exposes a REST API on port 80. All endpoints are accessible without authentication when connected to the device network. CORS is enabled for all GET requests (<code>allow_origins=["*"]</code>).

The software is source-available — freely available for private, educational and research use (CC BY-NC 4.0): [https://github.com/dahljo/bcmeter github.com/dahljo/bcmeter]

=== Status & Diagnostics ===

{| class="wikitable"
! Method !! Endpoint !! Description
|-
| GET || <code>/api/status</code> || Current measurement state, last sensor readings, error codes, sample count, WiFi mode, firmware version, OTA info. Returns <code>"env": "pi"</code> to distinguish from ESP32 (<code>"env": "esp32"</code>).
|-
| GET || <code>/api/system</code> || Hardware info: IP, MAC address, disk usage, memory, modem status, GPS detail, barometric altitude, geolocation, current time
|-
| GET || <code>/api/logs</code> || Structured health report as JSON with sections: <code>hardware</code>, <code>measurement</code>, <code>system</code>, <code>network</code>, <code>incidents</code>. Each entry has <code>{k, v, s}</code> (key, value, status: ok/warn/error/info).
|-
| GET || <code>/api/maintenance-logs</code> || Downloads a zip bundle containing: rotating bcmeter.log files, syslog, 10 newest CSV sessions, dmesg, journalctl for bcmeter and pigpiod services, config JSON, incident log.
|-
| GET || <code>/api/debug_mobile/status</code> || Returns modem debug send progress (from email handler).
|}

=== Measurement Control ===

All control is dispatched through a single endpoint with an <code>action</code> query parameter:

{| class="wikitable"
! Method !! Endpoint !! Description
|-
| GET || <code>/api/control?action=start</code> || Begin measurement session. Returns 409 if time not synced, 423 if never calibrated, 424 if calibration stale (>28 days). Add <code>&force=1</code> to override preflight checks.
|-
| GET || <code>/api/control?action=stop</code> || Stop measurement and save session file.
|-
| GET || <code>/api/control?action=calibrate</code> || Start calibration routine (returns 202 immediately — poll <code>/api/calibration</code> for progress). Requires sampling to be stopped.
|-
| GET || <code>/api/calibration</code> || Calibration status: <code>{running, done, ok, elapsed_ms, log}</code>.
|-
| GET || <code>/api/control?action=clear_error</code> || Reset error state to ERR_NONE.
|-
| GET || <code>/api/control?action=identify</code> || Triggers LED identify blink pattern (Morse code spelling "bcmeter" for 30 seconds). Useful for locating a specific device when multiple units are deployed.
|-
| GET || <code>/api/control?action=debug_mobile</code> || Triggers modem debug email via Lambda. Requires modem present.
|}

=== Configuration ===

{| class="wikitable"
! Method !! Endpoint !! Description
|-
| GET || <code>/api/config</code> || All settings as JSON. Each parameter includes type, value, label, tab, and description.
|-
| POST || <code>/api/config</code> || Update settings. JSON body with key-value pairs. Accepts <code>{key: value}</code> or <code>{key: {value: ...}}</code> format. Only changed values need to be sent. Triggers deferred modem onboarding if <code>mail_logs_to</code> is set.
|-
| POST || <code>/api/device/rename</code> || Set device name and hostname. Body: <code>{"name": "bcmeter01"}</code> (1–32 chars). Runs <code>hostnamectl set-hostname</code>.
|-
| GET || <code>/api/control?action=synctime&ts=EPOCH&tz=IANA</code> || Sync device clock. <code>ts</code> = Unix timestamp, <code>tz</code> = IANA timezone string (e.g. <code>Europe/Berlin</code>). Applies timezone via <code>timedatectl</code>.
|}

=== WiFi Management ===

{| class="wikitable"
! Method !! Endpoint !! Description
|-
| GET || <code>/api/wifi/scan</code> || List nearby networks: <code>{scanning: bool, networks: [{ssid, rssi, secure}]}</code>. Add <code>?refresh=1</code> to trigger a new background scan.
|-
| POST || <code>/api/wifi/scan/refresh</code> || Explicitly trigger a new WiFi scan (returns 202, or 409 if already scanning).
|-
| GET || <code>/api/wifi/status</code> || Current connection: <code>{mode, status, ssid, ip, rssi, quality (0-4), internet, timeSynced}</code>.
|-
| POST || <code>/api/wifi</code> || Save WiFi credentials. Body: <code>{"ssid": "...", "pass": "..."}</code> (password min 8 chars).
|-
| POST || <code>/api/wifi/connect</code> || Save credentials and initiate background connection attempt (returns 202). Password must be 8–63 chars. Body: <code>{"ssid": "...", "pass": "..."}</code>
|-
| GET || <code>/api/wifi/connect/status</code> || Connection progress: <code>{state: 0-3, elapsed, log, mode, ip, ssid, device_name, hostname}</code>. States: 0=idle, 1=connecting, 2=success, 3=failed. Poll after POST to <code>/api/wifi/connect</code>.
|-
| POST || <code>/api/wifi/delete</code> || Delete credentials and switch to AP mode (deferred 2s background switch).
|-
| GET || <code>/api/ap-security</code> || Hotspot security settings: <code>{secured: bool, password: str}</code>.
|-
| POST || <code>/api/ap-security</code> || Update hotspot password. Body: <code>{"secured": true, "password": "..."}</code> (min 8 chars).
|}

=== Data Management ===

{| class="wikitable"
! Method !! Endpoint !! Description
|-
| GET || <code>/api/csv</code> || Current session CSV data. Returns header-only if no active session. Add <code>?file=FILENAME</code> for archived files.
|-
| GET || <code>/api/files</code> || List stored CSV logs: <code>[{name, size, lines, date}]</code> sorted newest first.
|-
| GET || <code>/api/control?action=cleardata</code> || Delete all stored log files.
|}

=== Firmware Updates ===

{| class="wikitable"
! Method !! Endpoint !! Description
|-
| GET || <code>/api/ota/status</code> || Check if update available: <code>{available, version, url, sha256, notes, skipped}</code>.
|-
| POST || <code>/api/ota/check</code> || Force check for new firmware against GitHub Releases.
|-
| POST || <code>/api/ota/skip</code> || Skip current available update for this boot.
|-
| POST || <code>/api/ota/apply</code> || Download and apply firmware update. Returns 409 if none pending.
|-
| POST || <code>/api/update</code> || Direct firmware upload (.tar.gz or .zip archive). Extracts over the code directory and restarts <code>bcMeter.service</code> via <code>systemctl</code>. Stops active session first.
|}

=== System Operations ===

{| class="wikitable"
! Method !! Endpoint !! Description
|-
| GET || <code>/api/control?action=reboot</code> || End session and reboot the device (fire-and-forget thread via <code>sudo reboot</code>).
|-
| GET || <code>/api/control?action=shutdown</code> || Safely shut down via <code>sudo shutdown -h now</code>.
|-
| POST || <code>/api/email/validate</code> || Validate email API key against the Lambda endpoint. Body: <code>{"api_key": "..."}</code>. Returns <code>{valid: bool, error: str}</code>.
|}

=== Captive Portal ===

These endpoints handle captive portal detection on mobile devices and redirect to the main interface in AP mode:

{| class="wikitable"
! Endpoint !! Purpose
|-
| <code>/generate_204</code> || Android captive portal check
|-
| <code>/hotspot-detect.html</code> || Apple captive portal check
|-
| <code>/canonical.html</code> || Firefox captive portal check
|-
| <code>/ncsi.txt</code> || Windows captive portal check
|-
| <code>/success.txt</code> || Generic connectivity probe (returns <code>"success"</code>)
|}

=== Static Routes ===

{| class="wikitable"
! Path !! Description
|-
| <code>/</code> || Serves the SPA frontend (<code>interface/index.html</code>)
|-
| <code>/discover</code> || Standalone device discovery page (also hostable on bcmeter.org)
|-
| <code>/manual/*</code> || Static files from <code>interface/manual/</code>
|-
| <code>/current_log.csv</code> || Legacy redirect to <code>/api/csv</code>
|}

=== Example: Start a Measurement ===

<pre>
# Sync time first
curl "http://bcmeter-XXXX.local/api/control?action=synctime&ts=$(date +%s)&tz=Europe/Berlin"

# Start measurement
curl "http://bcmeter-XXXX.local/api/control?action=start"

# Poll status
curl "http://bcmeter-XXXX.local/api/status"

# Download current data
curl "http://bcmeter-XXXX.local/api/csv" -o measurement.csv
</pre>

Introduction

2026-06-08T10:35:01Z

Bcmwiki: Reframe: bcMeter (DIY) / source-available

== Introduction ==

The '''bcMeter''' is a source-available optical absorption photometer designed to measure Black Carbon (BC) aerosols — commonly known as soot — in real-time. The design is freely available for private, educational and research use (CC BY-NC 4.0); assembled instruments are offered on request. Whether you are monitoring ambient air quality in your neighborhood or measuring direct emissions from wood stoves, this device provides scientific-grade data at a fraction of the cost of reference instruments.

The device operates "headless" — it has no built-in screen. Instead, it hosts its own website that you can access from any smartphone or computer connected to the same network.

The software is source-available — freely available for private, educational and research use (CC BY-NC 4.0): [https://github.com/dahljo/bcmeter github.com/dahljo/bcmeter]

=== Device Types ===

* '''bcMeter (DIY)''' — The source-available, self-build version. Runs on a Raspberry Pi using the open PCB design, freely available for private, educational and research use (CC BY-NC 4.0). Build your own from the open design files and the Wiki (nothing is sold).
* '''bcMeter Kit''' — Assembled-instrument PCB plus components for self-assembly and 3D printing. Available on request.
* '''bcMeter Complete''' — Fully assembled, ready-to-use instrument on a compact platform that starts in seconds and updates over the air, with no microSD card or Linux system to maintain. Available on request.
* '''eBcMeter''' — Emission measurement instrument for direct source sampling from wood-burning stoves and similar combustion sources. Uses microgram (µg) units instead of nanogram (ng). Available on request.

=== How Does It Work? ===

[[File:Working principle of a bcMeter.png|300px|right]]

# Polluted air is drawn through filter paper by a pump
# The filter paper absorbs black carbon (BC) particles
# An LED shining at 880 nm passes through the filter; a sensor measures the attenuation (reduction in light intensity)
# A separate reference channel monitors the same LED through a clean portion of the filter, compensating for environmental changes
# The attenuation is converted to BC concentration (ng/m³) using Beer-Lambert law
# Data is saved as CSV and displayed in real-time on the web interface

'''Multi-wavelength:''' Optional 520 nm and 370 nm channels enable source apportionment via the Ångström Exponent (AAE) — distinguishing between fossil fuel and biomass burning sources.

=== Sensors & Capabilities ===

==== Core ====

{| class="wikitable"
! Measurement !! Sensor / Method !! Notes
|-
| Black Carbon (BC) || Optical absorption at 880 nm || Primary measurement
|-
| Source apportionment || 520 nm, 370 nm || Ångström Exponent
|-
| Temperature / Humidity || SHT4x ||
|-
| Airflow || Omron D6F differential pressure || Pump flow rate
|}

==== Optional Hardware ====

{| class="wikitable"
! Measurement !! Sensor / Method !! Notes
|-
| Temperature / Humidity / Pressure || BME280 || Barometric altitude
|-
| PM2.5 / PM10 || Sensirion SPS30 || Particulate matter
|-
| GPS || AT6668 UART || Position, altitude, speed
|-
| 4G Connectivity || SIM7080G LTE-M modem || Remote data upload
|}

Main Page

2026-06-08T10:34:59Z

Bcmwiki: Reframe: bcMeter (DIY) / source-available

== Welcome to the [https://bcmeter.org bcmeter.org] Wiki ==

The bcMeter wiki is the technical documentation hub for the bcMeter platform — an optical absorption photometer for measuring Black Carbon (BC) aerosols in real-time. The platform spans the source-available '''bcMeter (DIY)''' (build it yourself) and the ready-to-use '''bcMeter Kit, bcMeter Complete and eBcMeter''' instruments.

Whether you are setting up a new device, configuring measurements, or building your own unit, this wiki covers everything you need.

== Getting Started ==

* [[Introduction]] — What is bcMeter, how it works, capabilities
* [[Setup]] — Hardware requirements, first boot, WiFi configuration
* [[Interface]] — Web dashboard overview, status indicators, chart controls

== Using bcMeter ==

* [[Configuration]] — All settings: network, measurement, device, email
* [[Maintenance]] — Filter changes, calibration, data management
* [[Troubleshooting]] — Common issues and solutions
* [[Best practices]] — Environment, sampling, signal quality

== Technical Reference ==

* [[Developer mode]] — Hidden developer settings, hardware tuning
* [[API reference]] — REST API endpoints for automation and integration
* [[CSV data format]] — Column definitions and data structure
* [[Serial commands]] — USB debug interface

== bcMeter (DIY) — build it yourself ==

''These pages document the source-available bcMeter (DIY) — the Raspberry-Pi-based design, freely available for private, educational and research use (CC BY-NC 4.0), built from open design files (nothing is sold). The assembled bcMeter Kit, Complete and eBcMeter use a different hardware design.''

* [[Working principle]] — Optical measurement principle
* [[Bill of material]] — Component list and costs (bcMeter DIY)
* [[Device assembly]] — Hardware build instructions (bcMeter DIY)

== Software ==

The bcMeter software is source-available — freely available for private, educational and research use (CC BY-NC 4.0): '''[https://github.com/dahljo/bcmeter github.com/dahljo/bcmeter]'''

The codebase includes the web [[Interface|interface]], [[API reference|REST API]], measurement engine, and all device management functionality.

== Contact ==

* '''Technical inquiries & devices:''' Jonas Dahl — jd@bcmeter.org
* '''Black carbon science & air quality:''' Axel Friedrich — af@bcmeter.org
* '''Project website:''' [https://bcmeter.org bcmeter.org]

File:Bcmeter interface14.jpg

2026-05-02T20:30:59Z

Bcmwiki: Bcmwiki uploaded a new version of File:Bcmeter interface14.jpg