Difference between revisions of "Developer mode"

From bcmeter.org
Jump to navigation Jump to search
(Update: V1/V2 naming, remove ESP32/Pi distinction)
(Polish English manual/wiki wording)
 
(3 intermediate revisions by the same user not shown)
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 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 ===
=== 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. 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"
{| class="wikitable"
! Parameter !! Description !! Default
! Value !! Description
|-
| <code>median3</code> (default) || 3-sample median filter. Good default for rejecting isolated outliers.
|-
|-
| '''LED duty cycle (880nm)''' || Brightness of the 880nm IR LED (0–255) || Auto-set during calibration
| <code>ema</code> || Exponential moving average. Smoother trend, slower response to abrupt changes.
|-
|-
| '''LED duty cycle (520nm)''' || Brightness of the 520nm green LED || Auto-set
| <code>kalman</code> || Adaptive Kalman-style smoothing based on signal dynamics.
|}
 
==== Calibration (<code>dev:calibration</code>) ====
 
{| class="wikitable"
! Parameter !! Description !! Default
|-
|-
| '''LED duty cycle (370nm)''' || Brightness of the 370nm UV LED || Auto-set
| <code>sample_spot_diameter</code> || Sample spot diameter in cm. Used in BC mass concentration calculations. || 0.4
|-
|-
| '''Calibration factor K (per channel)''' || Ratio Ref/Sen from last calibration || Auto-set
| <code>filter_scattering_factor</code> || Filter scattering factor used by the optical correction model. || 1.39
|-
|-
| '''LED duty floor''' || Minimum duty before "no filter" is declared || 30
| <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
|-
|-
| '''Sample spot diameter''' || Diameter of the filter area exposed to sample air (cm). Critical for absorption calculation. || 0.4 cm
| <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
|-
|-
| '''Filter scattering factor''' || Correction factor for filter material light scattering || 1.39
| <code>cal_k_880nm</code> || Calibration factor for the 880 nm channel. || 1.0
|-
|-
| '''Number of channels''' || Active wavelength channels (1–3) || 1 (880nm only)
| <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 duty cycle''' || Base pump PWM speed (0–255) || 40
| <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
|-
|-
| '''Min pump duty''' || Minimum duty to maintain airflow || 35
| <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
|-
|-
| '''Max pump duty''' || Maximum pump speed limit || 255
| <code>afc_bc_low</code> || BC concentration below which AFC moves toward maximum flow. || 300 ng/m³
|-
|-
| '''Min airflow (mL)''' || Stall detection threshold || 70 mL/min
| <code>afc_bc_high</code> || BC concentration above which AFC moves toward minimum flow. || 2000 ng/m³
|-
|-
| '''PWM frequency''' || Pump control frequency (Hz) || 40
| <code>afc_flow_low</code> || Minimum airflow when AFC is active. || 0.05 L/min
|-
|-
| '''Disable pump control''' || Manual mode — bypasses automatic pump management || false
| <code>afc_flow_high</code> || Maximum airflow when AFC is active. || 0.7 L/min
|-
|-
| '''Enable 12V output''' || Activate 12V auxiliary power rail || false
| <code>afc_slope_gain</code> || Flow boost per 100 ng/min downward BC trend. || 0.05
|}
|}


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


{| class="wikitable"
{| class="wikitable"
! Parameter !! Description !! Default
! Parameter !! Description !! Default
|-
|-
| '''AFC flow low''' || Minimum airflow when AFC is active || 0.05 L/min
| <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
|-
|-
| '''AFC flow high''' || Maximum airflow when AFC is active || 0.5 L/min
| <code>iot_enable</code> || 4G / IoT modem connectivity is available. || true
|-
|-
| '''AFC BC low/high''' || BC concentration thresholds for flow lookup table || Varies
| <code>show_undervoltage_warning</code> || Show warning when the optical 12V rail / ADC is not detected. || false
|}
|}


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


{| class="wikitable"
{| class="wikitable"
! Parameter !! Description !! Default
! Parameter !! Description !! Default
|-
|-
| '''is_ebcMeter''' || Enable direct emission mode (µg units instead of ng) || false
| <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
|-
|-
| '''IoT enable''' || 4G/LTE modem available || false
| <code>onboarding_step_two</code> || Phase 2 onboarding complete: calibration and data sharing choice. || false
|-
|-
| '''Enable WiFi''' || WiFi connectivity available || true
| <code>onboarding_email_sent</code> || Welcome/access email has already been sent. || false
|-
|-
| '''Show undervoltage warning''' || Display warning when 12V rail not detected || true
| <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
|}
|}


==== System (dev:system) ====
=== 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.


Internal system parameters. Modifying these may affect device stability.
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 ===
=== 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>
Line 102: Line 174:
=== 12V Power Warning ===
=== 12V Power Warning ===


If the optical ADC is not detected (because 12V power is missing), a warning modal appears:
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 (5V) are unaffected.</blockquote>
<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>


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

Latest revision as of 22:15, 2 May 2026

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

  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. The values below match the current ESP32 firmware defaults in cfgstore.cpp.

BC Smoothing Algorithm

The first control selects the 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 set. 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 matching onboarding step flag to the device.

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=383"