Difference between revisions of "Developer mode"

From bcmeter.org
Jump to navigation Jump to search
(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)
(Update bcMeter ESP32 interface documentation and terminology (May 2026))
Line 1: Line 1:
== Developer Mode ==
== 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.
The bcMeter interface includes a hidden developer mode for advanced hardware tuning and diagnostics. '''Changes in developer mode affect hardware directly''' and can make measurements unusable when set incorrectly. Use it for support, development, and device-specific provisioning only.


=== Activating Developer Mode ===
=== Activating Developer Mode ===


# Open '''Settings''' (gear icon).
# Open '''Settings'''.
# Click on the '''device name''' text (next to "Configuration") '''7 times within 3 seconds'''.
# Click the '''device name''' text next to "Configuration" '''7 times within 3 seconds'''.
# The name will change to show <code>[DEV]</code> in yellow.
# The name changes to include <code>[DEV]</code>.
# A new '''Developer''' tab appears in the settings panel.
# A new '''⚠ Dev''' tab appears in the settings panel.


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


=== Developer Settings ===
=== Developer Tab Layout ===


The Developer tab exposes low-level configuration organized into sections:
The Developer tab opens with a warning banner:


==== Calibration (dev:calibration) ====
<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. Values below reflect the current ESP32 firmware defaults in <code>cfgstore.cpp</code>.
 
==== BC Smoothing Algorithm ====
 
The first control selects the real-time 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"
{| class="wikitable"
! 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
| <code>sample_spot_diameter</code> || Sample spot diameter in cm. Used in BC mass concentration calculations. || 0.4
|-
|-
| '''Filter scattering factor''' || Correction factor for filter material light scattering || 1.39
| <code>filter_scattering_factor</code> || Filter scattering factor used by the optical correction model. || 1.39
|-
|-
| '''Device correction factor''' || Device-specific correction factor for BC calculation || 1.0
| <code>device_specific_correction_factor</code> || Per-device correction factor from lab comparison or provisioning. || 1.0
|}
|}


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


{| class="wikitable"
{| class="wikitable"
! Parameter !! Description !! Default
! Parameter !! Description !! Default
|-
|-
| '''880nm IR LED brightness''' || Duty cycle for the 880nm IR LED (0–255) || 100 (auto-set during calibration)
| <code>burst_measurement</code> || LED is only enabled during the final seconds of a sample cycle. Experimental power/thermal mode. || false
|-
|-
| '''520nm Green LED brightness''' || Duty cycle for the 520nm green LED (0–255) || 255 (auto-set)
| <code>adc_block_samples</code> || ADC samples per sensor/reference block. Higher values reduce noise and increase capture time. || 256
|-
|-
| '''370nm UV LED brightness''' || Duty cycle for the 370nm UV LED (0–255) || 255 (auto-set)
| <code>led_duty_cycle_370nm</code> || UV LED brightness/PWM duty for 370 nm channel. || 255
|-
|-
| '''Calibration factor 880nm''' || K factor (Ref/Sen ratio) from last calibration || 1.0 (auto-set)
| <code>led_duty_cycle_520nm</code> || Green LED brightness/PWM duty for 520 nm channel. || 255
|-
|-
| '''Calibration factor 520nm''' || K factor for 520nm channel || 1.0 (auto-set)
| <code>led_duty_cycle_880nm</code> || IR LED brightness/PWM duty for 880 nm channel. || 100
|-
|-
| '''Calibration factor 370nm''' || K factor for 370nm channel || 1.0 (auto-set)
| <code>cal_k_370nm</code> || Calibration factor for the 370 nm channel. || 1.0
|-
|-
| '''Min ADC voltage before error''' || Minimum acceptable ADC voltage (V) before triggering ERR_ADC_LOW || 0.5
| <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 (dev:pump) ====
==== Pump (<code>dev:pump</code>) ====


{| class="wikitable"
{| class="wikitable"
! Parameter !! Description !! Default
! Parameter !! Description !! Default
|-
|-
| '''Pump power''' || Base pump PWM duty cycle (0–255) || 20
| <code>pump_dutycycle</code> || Base pump power/PWM duty. || 20
|-
|-
| '''Minimum pump duty cycle''' || Minimum duty to maintain airflow || 35
| <code>max_pump_duty</code> || Maximum pump duty cycle. || 255
|-
|-
| '''Maximum pump duty cycle''' || Maximum pump speed limit || 255
| <code>min_pump_duty</code> || Minimum pump duty cycle. || 1
|-
|-
| '''Minimum airflow (ml/min)''' || Stall detection threshold || 70
| <code>min_airflow_ml</code> || Minimum airflow before stall recovery starts, in ml/min. || 70
|-
|-
| '''PWM frequency''' || Pump control frequency (Hz) || 40
| <code>twelvevolt_duty</code> || 12V pump output duty cycle. || 20
|-
|-
| '''12V pump duty cycle''' || Duty cycle for 12V pump || 20
| <code>reverse_dutycycle</code> || Reverse pump duty-cycle handling for hardware variants. || false
|-
|-
| '''Reverse pump duty cycle''' || Reverse the duty cycle logic || false
| <code>disable_pump_control</code> || Disable internal pump control loop. Use only with external control hardware. || false
|-
|-
| '''Enable 12V power output''' || Activate 12V auxiliary power rail || false
| <code>TWELVEVOLT_ENABLE</code> || Enable 12V power output. || false
|-
|-
| '''Log pump duty cycle per sample''' || Include pump duty in CSV output || false
| <code>log_pump_duty</code> || Write pump duty cycle into the CSV per sample. || false
|}
|}


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


{| class="wikitable"
{| class="wikitable"
! Parameter !! Description !! Default
! Parameter !! Description !! Default
|-
|-
| '''AFC: BC below this = max flow''' || BC threshold (ng/m³) below which maximum airflow is used || 300
| <code>afc_bc_low</code> || BC concentration below which AFC moves toward maximum flow. || 300 ng/m³
|-
|-
| '''AFC: BC above this = min flow''' || BC threshold (ng/m³) above which minimum airflow is used || 2000
| <code>afc_bc_high</code> || BC concentration above which AFC moves toward minimum flow. || 2000 ng/m³
|-
|-
| '''AFC: min airflow''' || Minimum airflow when AFC is active (LPM) || 0.05
| <code>afc_flow_low</code> || Minimum airflow when AFC is active. || 0.05 L/min
|-
|-
| '''AFC: max airflow''' || Maximum airflow when AFC is active (LPM) || 0.7
| <code>afc_flow_high</code> || Maximum airflow when AFC is active. || 0.7 L/min
|-
|-
| '''AFC: flow boost per 100ng/min descent''' || Slope gain for rapid BC decrease || 0.05
| <code>afc_slope_gain</code> || Flow boost per 100 ng/min downward BC trend. || 0.05
|}
|}


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


{| class="wikitable"
{| class="wikitable"
! Parameter !! Description !! Default
! Parameter !! Description !! Default
|-
|-
| '''Enable WiFi''' || WiFi connectivity available || true
| <code>airflow_sensor</code> || Airflow sensor is installed and should be used. || true
|-
|-
| '''4G/IOT connectivity''' || 4G/LTE modem available || false
| <code>af_sensor_type</code> || Airflow sensor type: 0 = P0001A1, 1 = P0010A2. || 1
|-
|-
| '''Swap data channels''' || Swap sensor/reference ADC channels || false
| <code>enable_wifi</code> || WiFi connectivity is available. || true
|-
|-
| '''Reference voltage for SPI ADC''' || ADC reference voltage (V) || 4.096
| <code>iot_enable</code> || 4G / IoT modem connectivity is available. || true
|-
|-
| '''Device has display''' || Enable SSD1306 display support || false
| <code>show_undervoltage_warning</code> || Show warning when the optical 12V rail / ADC is not detected. || false
|}
|}


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


{| class="wikitable"
{| class="wikitable"
! Parameter !! Description !! Default
! Parameter !! Description !! Default
|-
|-
| '''Number of channels''' || Active wavelength channels (1–3) || 1 (880nm only)
| <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 configured. || email_service_password
|-
|-
| '''Direct emission measurement mode''' || Enable µg units instead of ng (for emission monitoring) || false
| <code>onboarding_step_one</code> || Phase 1 onboarding complete: contact email and WiFi setup. || false
|-
|-
| '''Device name''' || Internal device name || "bcMeter"
| <code>onboarding_step_two</code> || Phase 2 onboarding complete: calibration and data sharing choice. || false
|-
|-
| '''Enable heating''' || Activate internal heater || 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
|}
|}


Internal system parameters like onboarding state, email service credentials, and team upload settings are also stored here but are managed automatically.
=== Onboarding State ===
 
=== CLI Debug Mode ===


Running <code>python main.py --debug</code> on the device sets debug mode:
The current firmware stores onboarding progress with separate flags:


* '''API server is skipped entirely''' — uvicorn is not started; the process blocks on a stop event.
* <code>onboarding_step_one</code>: WiFi/email phase completed.
* '''Measurement auto-starts immediately''' — bypasses the "never calibrated" guard.
* <code>onboarding_step_two</code>: calibration/data-sharing phase completed.
* '''Verbose ADC output streams to stdout.'''
* <code>onboarding_email_sent</code>: welcome email has already been sent.
* Use <code>Ctrl-C</code> to stop.


This is primarily intended for hardware-level ADC testing on-device without the web interface overhead.
The browser also uses local storage and cookies for temporary "Skip for now" behavior. "Don't show again" writes the respective onboarding step flag to the device configuration.


=== Development Build Detection ===
=== Development Build Detection ===


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


=== Identify Device ===
=== 12V Power Warning ===


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.
If the optical ADC is not detected, the interface can show a 12V warning:


* '''API call:''' <code>/api/control?action=identify</code>
<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>
* '''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 ===
=== Development Device Variants ===


The welcome/onboarding screen can be bypassed:
The <code>bcmeter-dev</code> Raspberry Pi codebase is useful for development and older prototypes, but it differs from the ESP32 production firmware. Device-specific differences should be treated as implementation details of the same function:


* '''Skip for now:''' Hides for 2 days (stored in localStorage + cookie).
* '''Networking:''' Raspberry Pi builds may use Flask and NetworkManager, while ESP32 builds use the embedded web server and ESP-IDF WiFi stack.
* '''Don't show again:''' Permanently disables onboarding by writing <code>onboarding_done: true</code> to device config.
* '''Optics/ADC:''' Pi builds may reference ADS8344E or MCP342X hardware; current ESP32 V2 builds use ADS1220-based optical acquisition.
* '''Firmware updates:''' Pi development devices may update through OS/GitHub release workflows, while ESP32 devices use OTA firmware images.
* '''Sensors:''' Development devices may expose DS18B20 or other prototype sensors that are not present on every ESP32 unit.

Revision as of 21:58, 2 May 2026

Developer Mode

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

Activating Developer Mode

  1. Open Settings.
  2. Click the device name text next to "Configuration" 7 times within 3 seconds.
  3. The name changes to include [DEV].
  4. 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:

Developer mode — changes affect hardware directly. Save only if you know what you are doing.

Settings are grouped by namespace. Values below reflect the current ESP32 firmware defaults in cfgstore.cpp.

BC Smoothing Algorithm

The first control selects the real-time BC smoothing algorithm. This setting is stored as bc_filter.

Value Description
median3 (default) 3-sample median filter. Good default for rejecting isolated outliers.
ema Exponential moving average. Smoother trend, slower response to abrupt changes.
kalman Adaptive Kalman-style smoothing based on signal dynamics.

Calibration (dev:calibration)

Parameter Description Default
sample_spot_diameter Sample spot diameter in cm. Used in BC mass concentration calculations. 0.4
filter_scattering_factor Filter scattering factor used by the optical correction model. 1.39
device_specific_correction_factor Per-device correction factor from lab comparison or provisioning. 1.0

Optical (dev:optical)

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

Pump (dev:pump)

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

Auto Flow Control (dev:afc)

Parameter Description Default
afc_bc_low BC concentration below which AFC moves toward maximum flow. 300 ng/m³
afc_bc_high BC concentration above which AFC moves toward minimum flow. 2000 ng/m³
afc_flow_low Minimum airflow when AFC is active. 0.05 L/min
afc_flow_high Maximum airflow when AFC is active. 0.7 L/min
afc_slope_gain Flow boost per 100 ng/min downward BC trend. 0.05

Hardware (dev:hardware)

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

System (dev:system)

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

Onboarding State

The current firmware stores onboarding progress with separate flags:

  • onboarding_step_one: WiFi/email phase completed.
  • onboarding_step_two: calibration/data-sharing phase completed.
  • onboarding_email_sent: 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 respective onboarding step flag to the device configuration.

Development Build Detection

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

DEVELOPMENT BUILD — connected to dev backend

12V Power Warning

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

⚠ 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.

Development Device Variants

The bcmeter-dev Raspberry Pi codebase is useful for development and older prototypes, but it differs from the ESP32 production firmware. 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: Pi development devices may update through OS/GitHub release workflows, while ESP32 devices use OTA firmware images.
  • Sensors: Development devices may expose DS18B20 or other prototype sensors that are not present on every ESP32 unit.
Retrieved from "https://bcmeter.org/wiki/index.php?title=Developer_mode&oldid=351"