Difference between revisions of "Developer mode"

From bcmeter.org
Jump to navigation Jump to search
(Add Identify Device section (Morse code LED blink))
(Update dev mode to match actual bcmeter-dev config.py: restructured sections (calibration vs optical), added all actual parameters with correct defaults, added CLI debug mode docs, added AFC slope_gain, hardware swap_channels/spi_vref/display params)
 
Line 21: Line 21:
! Parameter !! Description !! Default
! Parameter !! Description !! Default
|-
|-
| '''LED duty cycle (880nm)''' || Brightness of the 880nm IR LED (0–255) || Auto-set during calibration
| '''Sample spot diameter''' || Diameter of the filter area exposed to sample air (cm). Critical for absorption calculation. || 0.4 cm
|-
|-
| '''LED duty cycle (520nm)''' || Brightness of the 520nm green LED || Auto-set
| '''Filter scattering factor''' || Correction factor for filter material light scattering || 1.39
|-
| '''LED duty cycle (370nm)''' || Brightness of the 370nm UV LED || Auto-set
|-
| '''Calibration factor K (per channel)''' || Ratio Ref/Sen from last calibration || Auto-set
|-
|-
| '''LED duty floor''' || Minimum duty before "no filter" is declared || 30
| '''Device correction factor''' || Device-specific correction factor for BC calculation || 1.0
|}
|}


Line 37: Line 33:
! Parameter !! Description !! Default
! Parameter !! Description !! Default
|-
|-
| '''Sample spot diameter''' || Diameter of the filter area exposed to sample air (cm). Critical for absorption calculation. || 0.4 cm
| '''880nm IR LED brightness''' || Duty cycle for the 880nm IR LED (0–255) || 100 (auto-set during calibration)
|-
| '''520nm Green LED brightness''' || Duty cycle for the 520nm green LED (0–255) || 255 (auto-set)
|-
| '''370nm UV LED brightness''' || Duty cycle for the 370nm UV LED (0–255) || 255 (auto-set)
|-
| '''Calibration factor 880nm''' || K factor (Ref/Sen ratio) from last calibration || 1.0 (auto-set)
|-
| '''Calibration factor 520nm''' || K factor for 520nm channel || 1.0 (auto-set)
|-
|-
| '''Filter scattering factor''' || Correction factor for filter material light scattering || 1.39
| '''Calibration factor 370nm''' || K factor for 370nm channel || 1.0 (auto-set)
|-
|-
| '''Number of channels''' || Active wavelength channels (1–3) || 1 (880nm only)
| '''Min ADC voltage before error''' || Minimum acceptable ADC voltage (V) before triggering ERR_ADC_LOW || 0.5
|}
|}


Line 49: Line 53:
! Parameter !! Description !! Default
! Parameter !! Description !! Default
|-
|-
| '''Pump duty cycle''' || Base pump PWM speed (0–255) || 40
| '''Pump power''' || Base pump PWM duty cycle (0–255) || 20
|-
|-
| '''Min pump duty''' || Minimum duty to maintain airflow || 35
| '''Minimum pump duty cycle''' || Minimum duty to maintain airflow || 35
|-
|-
| '''Max pump duty''' || Maximum pump speed limit || 255
| '''Maximum pump duty cycle''' || Maximum pump speed limit || 255
|-
|-
| '''Min airflow (mL)''' || Stall detection threshold || 70 mL/min
| '''Minimum airflow (ml/min)''' || Stall detection threshold || 70
|-
|-
| '''PWM frequency''' || Pump control frequency (Hz) || 40
| '''PWM frequency''' || Pump control frequency (Hz) || 40
|-
|-
| '''Disable pump control''' || Manual mode — bypasses automatic pump management || false
| '''12V pump duty cycle''' || Duty cycle for 12V pump || 20
|-
| '''Reverse pump duty cycle''' || Reverse the duty cycle logic || false
|-
|-
| '''Enable 12V output''' || Activate 12V auxiliary power rail || false
| '''Enable 12V power output''' || Activate 12V auxiliary power rail || false
|-
| '''Log pump duty cycle per sample''' || Include pump duty in CSV output || false
|}
|}


Line 69: Line 77:
! Parameter !! Description !! Default
! Parameter !! Description !! Default
|-
|-
| '''AFC flow low''' || Minimum airflow when AFC is active || 0.05 L/min
| '''AFC: BC below this = max flow''' || BC threshold (ng/m³) below which maximum airflow is used || 300
|-
| '''AFC: BC above this = min flow''' || BC threshold (ng/m³) above which minimum airflow is used || 2000
|-
| '''AFC: min airflow''' || Minimum airflow when AFC is active (LPM) || 0.05
|-
|-
| '''AFC flow high''' || Maximum airflow when AFC is active || 0.5 L/min
| '''AFC: max airflow''' || Maximum airflow when AFC is active (LPM) || 0.7
|-
|-
| '''AFC BC low/high''' || BC concentration thresholds for flow lookup table || Varies
| '''AFC: flow boost per 100ng/min descent''' || Slope gain for rapid BC decrease || 0.05
|}
|}


Line 81: Line 93:
! Parameter !! Description !! Default
! Parameter !! Description !! Default
|-
|-
| '''is_ebcMeter''' || Enable direct emission mode (µg units instead of ng) || false
| '''Enable WiFi''' || WiFi connectivity available || true
|-
|-
| '''IoT enable''' || 4G/LTE modem available || false
| '''4G/IOT connectivity''' || 4G/LTE modem available || false
|-
|-
| '''Enable WiFi''' || WiFi connectivity available || true
| '''Swap data channels''' || Swap sensor/reference ADC channels || false
|-
| '''Reference voltage for SPI ADC''' || ADC reference voltage (V) || 4.096
|-
|-
| '''Show undervoltage warning''' || Display warning when 12V rail not detected || true
| '''Device has display''' || Enable SSD1306 display support || false
|}
|}


==== System (dev:system) ====
==== System (dev:system) ====


Internal system parameters. Modifying these may affect device stability.
{| class="wikitable"
! Parameter !! Description !! Default
|-
| '''Number of channels''' || Active wavelength channels (1–3) || 1 (880nm only)
|-
| '''Direct emission measurement mode''' || Enable µg units instead of ng (for emission monitoring) || false
|-
| '''Device name''' || Internal device name || "bcMeter"
|-
| '''Enable heating''' || Activate internal heater || false
|}


=== Development Build Detection ===
Internal system parameters like onboarding state, email service credentials, and team upload settings are also stored here but are managed automatically.


When the device is running a development build, the API returns <code>"env":"dev"</code> in the status response and a red banner appears at the top of the interface:
=== CLI Debug Mode ===


<blockquote style="background:#dc3545;color:#fff;padding:8px 16px;border-radius:4px;">DEVELOPMENT BUILD — connected to dev backend</blockquote>
Running <code>python main.py --debug</code> on the device sets debug mode:


=== 12V Power Warning ===
* '''API server is skipped entirely''' — uvicorn is not started; the process blocks on a stop event.
* '''Measurement auto-starts immediately''' — bypasses the "never calibrated" guard.
* '''Verbose ADC output streams to stdout.'''
* Use <code>Ctrl-C</code> to stop.


If the optical ADC is not detected (because 12V power is missing), a warning modal appears:
This is primarily intended for hardware-level ADC testing on-device without the web interface overhead.


<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 (5V) are unaffected.</blockquote>
=== Development Build Detection ===


=== Onboarding Skip Mechanism ===
When the device is running a development build, the API returns <code>"env":"dev"</code> in the status response and a red banner appears at the top of the interface:


The welcome/onboarding screen can be bypassed:
<blockquote style="background:#dc3545;color:#fff;padding:8px 16px;border-radius:4px;">DEVELOPMENT BUILD — connected to dev backend</blockquote>
 
* '''Skip for now:''' Hides for 2 days (stored in localStorage + cookie).
* '''Don't show again:''' Permanently disables onboarding by writing <code>onboarding_done: true</code> to device config.


=== Identify Device ===
=== Identify Device ===
Line 121: Line 145:
* '''Pattern:''' Morse code at ~10 WPM (dot = 120 ms, dash = 360 ms)
* '''Pattern:''' Morse code at ~10 WPM (dot = 120 ms, dash = 360 ms)
* '''LED reverts''' to its previous mode (idle, sampling, or error) after the pattern completes.
* '''LED reverts''' to its previous mode (idle, sampling, or error) after the pattern completes.
=== Onboarding Skip Mechanism ===
The welcome/onboarding screen can be bypassed:
* '''Skip for now:''' Hides for 2 days (stored in localStorage + cookie).
* '''Don't show again:''' Permanently disables onboarding by writing <code>onboarding_done: true</code> to device config.

Latest revision as of 20:25, 31 March 2026

Developer Mode

The bcMeter interface includes a hidden developer mode for advanced hardware tuning and diagnostics. Changes in developer mode affect hardware directly — only modify settings if you understand their impact.

Activating Developer Mode

  1. Open Settings (gear icon).
  2. Click on the device name text (next to "Configuration") 7 times within 3 seconds.
  3. The name will change to show [DEV] in yellow.
  4. A new Developer tab appears in the settings panel.

Developer mode persists until the page is reloaded.

Developer Settings

The Developer tab exposes low-level configuration organized into sections:

Calibration (dev:calibration)

Parameter Description Default
Sample spot diameter Diameter of the filter area exposed to sample air (cm). Critical for absorption calculation. 0.4 cm
Filter scattering factor Correction factor for filter material light scattering 1.39
Device correction factor Device-specific correction factor for BC calculation 1.0

Optical (dev:optical)

Parameter Description Default
880nm IR LED brightness Duty cycle for the 880nm IR LED (0–255) 100 (auto-set during calibration)
520nm Green LED brightness Duty cycle for the 520nm green LED (0–255) 255 (auto-set)
370nm UV LED brightness Duty cycle for the 370nm UV LED (0–255) 255 (auto-set)
Calibration factor 880nm K factor (Ref/Sen ratio) from last calibration 1.0 (auto-set)
Calibration factor 520nm K factor for 520nm channel 1.0 (auto-set)
Calibration factor 370nm K factor for 370nm channel 1.0 (auto-set)
Min ADC voltage before error Minimum acceptable ADC voltage (V) before triggering ERR_ADC_LOW 0.5

Pump (dev:pump)

Parameter Description Default
Pump power Base pump PWM duty cycle (0–255) 20
Minimum pump duty cycle Minimum duty to maintain airflow 35
Maximum pump duty cycle Maximum pump speed limit 255
Minimum airflow (ml/min) Stall detection threshold 70
PWM frequency Pump control frequency (Hz) 40
12V pump duty cycle Duty cycle for 12V pump 20
Reverse pump duty cycle Reverse the duty cycle logic false
Enable 12V power output Activate 12V auxiliary power rail false
Log pump duty cycle per sample Include pump duty in CSV output false

Auto Flow Control (dev:afc)

Parameter Description Default
AFC: BC below this = max flow BC threshold (ng/m³) below which maximum airflow is used 300
AFC: BC above this = min flow BC threshold (ng/m³) above which minimum airflow is used 2000
AFC: min airflow Minimum airflow when AFC is active (LPM) 0.05
AFC: max airflow Maximum airflow when AFC is active (LPM) 0.7
AFC: flow boost per 100ng/min descent Slope gain for rapid BC decrease 0.05

Hardware (dev:hardware)

Parameter Description Default
Enable WiFi WiFi connectivity available true
4G/IOT connectivity 4G/LTE modem available false
Swap data channels Swap sensor/reference ADC channels false
Reference voltage for SPI ADC ADC reference voltage (V) 4.096
Device has display Enable SSD1306 display support false

System (dev:system)

Parameter Description Default
Number of channels Active wavelength channels (1–3) 1 (880nm only)
Direct emission measurement mode Enable µg units instead of ng (for emission monitoring) false
Device name Internal device name "bcMeter"
Enable heating Activate internal heater false

Internal system parameters like onboarding state, email service credentials, and team upload settings are also stored here but are managed automatically.

CLI Debug Mode

Running python main.py --debug on the device sets debug mode:

  • API server is skipped entirely — uvicorn is not started; the process blocks on a stop event.
  • Measurement auto-starts immediately — bypasses the "never calibrated" guard.
  • Verbose ADC output streams to stdout.
  • Use Ctrl-C to stop.

This is primarily intended for hardware-level ADC testing on-device without the web interface overhead.

Development Build Detection

When the device is running a development build, the API returns "env":"dev" in the status response and a red banner appears at the top of the interface:

DEVELOPMENT BUILD — connected to dev backend

Identify Device

The Developer tab includes an Identify Device button that blinks the status LED in a distinctive Morse code pattern (spelling "bcmeter") for 30 seconds. This helps visually locate a specific device when multiple units are deployed in the same area.

  • API call: /api/control?action=identify
  • Duration: 30 seconds
  • Pattern: Morse code at ~10 WPM (dot = 120 ms, dash = 360 ms)
  • LED reverts to its previous mode (idle, sampling, or error) after the pattern completes.

Onboarding Skip Mechanism

The welcome/onboarding screen can be bypassed:

  • Skip for now: Hides for 2 days (stored in localStorage + cookie).
  • Don't show again: Permanently disables onboarding by writing onboarding_done: true to device config.
Retrieved from "https://bcmeter.org/wiki/index.php?title=Developer_mode&oldid=346"