Maintenance - Revision history

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

2026-06-08T18:59:35Z

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

← Older revision		Revision as of 18:59, 8 June 2026
Line 32:		Line 32:
	# Wait for "Calibration Successful" before starting a new log.		# 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~~. Current ESP32 builds use ADS1220 block averaging for the optical readings~~. Calibration typically takes 30–60 seconds.		'''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 ===		=== Data Management ===

	~~Data is stored on the device's internal flash storage (LittleFS) and persists across reboots.~~

	Click '''Log Files''' to open the data manager. The modal lists all stored sessions:		Click '''Log Files''' to open the data manager. The modal lists all stored sessions:
Line 43:		Line 41:
	! Column !! Description		! Column !! Description
	\|-		\|-
	\| '''Log''' \|\| Session name or filename (e.g., <code>~~bcmeter_20260312_2126~~.csv</code>). "Current Session" shows the active log.		\| '''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.		\| '''Size''' \|\| File size in KB, or number of data points for the current session.
Line 57:		Line 55:

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

	'''Storage management:''' The device has ~2 MB internal flash for logs. Warning at 512 KB free, critical at 32 KB. Old logs are auto-deleted when critical threshold is reached. Empty files are cleaned on startup.

	=== Device Management ===		=== Device Management ===
Line 73:		Line 69:
	* '''Reboot Device:''' Restarts the device.		* '''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.		* '''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 ~~(.bin)~~. The device also checks for updates a few times a day.		* '''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.		* '''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.

Line 113:		Line 109:

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

Bcmwiki: Polish English manual/wiki wording

2026-05-02T20:15:57Z

Polish English manual/wiki wording

← Older revision		Revision as of 20:15, 2 May 2026
Line 1:		Line 1:
	== Maintenance Procedures ==		== Maintenance Procedures ==

	~~Access~~ maintenance functions ~~via~~ the '''Maintenance''' button in the navigation bar. The modal ~~is organized into~~ cards for device management, system status, time synchronization, and geolocation.		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 ===		=== Filter Change Procedure ===
Line 19:		Line 19:
	# Insert a new filter with '''markings facing up'''.		# Insert a new filter with '''markings facing up'''.
	# Screw the cap back on (hand-tight).		# Screw the cap back on (hand-tight).
	# '''Check hose''' (if used): ~~ensure~~ the air hose ~~remains~~ connected to the inlet port.		# '''Check hose''' (if used): check that the air hose is still connected to the inlet port.
	# '''Run [[Maintenance#Calibration\|Calibration]] (required).'''		# '''Run [[Maintenance#Calibration\|Calibration]] (required).'''

Line 27:		Line 27:

	# Go to '''Maintenance''' > '''Calibrate Device'''.		# Go to '''Maintenance''' > '''Calibrate Device'''.
	# ~~Ensure~~ a '''new and clean filter''' is installed.		# Check that a '''new and clean filter''' is installed.
	# Click "Yes."		# Click "Yes."
	# A progress bar appears. The device adjusts LED intensity per channel to find stable reference and sensor readings.		# A progress bar appears. The device adjusts LED intensity per channel to find stable reference and sensor readings.
Line 38:		Line 38:
	Data is stored on the device's internal flash storage (LittleFS) and persists across reboots.		Data is stored on the device's internal flash storage (LittleFS) and persists across reboots.

	Click '''Log Files''' to open the data manager. The modal ~~displays a table listing~~ all stored sessions:		Click '''Log Files''' to open the data manager. The modal lists all stored sessions:

	{\| class="wikitable"		{\| class="wikitable"
Line 67:		Line 67:
	* '''View System Status:''' Opens a structured status report for diagnosing issues. Entries are grouped by category: hardware, measurement, system, network.		* '''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.		* '''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 ~~correct physical device~~ when ~~multiple bcMeters are~~ nearby.		* '''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 ====		==== System Operations ====

	* '''Reboot Device:''' Restarts the device.		* '''Reboot Device:''' Restarts the device.
	* '''Shutdown Device:''' ~~Safely powers off to prevent data corruption~~. ~~Always use~~ this before ~~unplugging~~. If the device loses power during a session ~~without proper shutdown~~, it ~~will automatically resume~~ measurement on next boot.		* '''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 ~~manually~~ upload a firmware file (.bin). The device also checks for updates ~~automatically~~ a few times a day.		* '''Manual Firmware Update:''' Opens a dialog to upload a firmware file (.bin). 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.		* '''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.

Line 88:		Line 88:
	=== System Status ===		=== System Status ===

	~~Displays~~ device information:		Shows device information:

	* '''Device ID:''' Unique hardware identifier (MAC address).		* '''Device ID:''' Unique hardware identifier (MAC address).
Line 97:		Line 97:
	=== Time Synchronization ===		=== Time Synchronization ===

	~~Critical for accurate data~~ timestamps, especially ~~for~~ devices without internet.		Accurate timestamps need a correct device clock, especially on devices without internet access.

	* '''Browser Time / Device Time:''' Displayed for comparison.		* '''Browser Time / Device Time:''' Displayed for comparison.
Line 106:		Line 106:
	=== Geolocation ===		=== Geolocation ===

	When location services are active (Settings > Measurement > Location), a Geolocation card ~~displays~~:		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.		* '''Location:''' Latitude/longitude with source (GPS, cell tower, or IP-based) and accuracy indicator.
Line 112:		Line 112:
	* '''Altitude (GPS) & Speed:''' Shown when a GPS module is connected and has a fix.		* '''Altitude (GPS) & Speed:''' Shown when a GPS module is connected and has a fix.

	The location input ~~supports multiple~~ formats: <code>48.2082, 16.3738</code> — <code>48.2082 16.3738</code> — <code>(48.2082; 16.3738)</code> ~~etc~~.		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>.

Bcmwiki: Update bcMeter ESP32 interface documentation and terminology (May 2026)

2026-05-02T19:58:43Z

Update bcMeter ESP32 interface documentation and terminology (May 2026)

← Older revision		Revision as of 19:58, 2 May 2026
Line 10:		Line 10:
	* The '''marked side must face UP''' (towards the LEDs/light source in the upper optical chamber).		* 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~~. Do not bend or fold the filter. Creases damage the filter surface and cause unreliable measurements~~.		'''Warning:''' Incorrect orientation (marked side down) results in ~30% measurement error.

	'''Procedure:'''		'''Procedure:'''

	# Stop running session.		# Stop any running session.
	# Unscrew the top cap of the optical chamber.		# Unscrew the top cap of the optical chamber.
	# Remove the saturated filter.		# Remove the saturated filter.
	~~# Check the air inlet for filter paper residue and '''remove if present'''.~~
	# Insert a new filter with '''markings facing up'''.		# Insert a new filter with '''markings facing up'''.
	# Screw the cap back on (hand-tight).		# Screw the cap back on (hand-tight).
Line 25:		Line 24:
	=== Calibration ===		=== Calibration ===

	Calibration balances the sensor signal against the reference signal for the specific filter currently installed ~~and should ideally be processed on every filter change — although the calibration factor will change extremely slowly once determined~~.		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'''.		# Go to '''Maintenance''' > '''Calibrate Device'''.
	# Ensure a '''new and clean filter''' is installed.		# Ensure a '''new and clean filter''' is installed.
	# Click "Yes."		# Click "Yes."
	# A progress bar appears. The device adjusts LED intensity per channel ~~using binary search~~ to find ~~optimal duty cycles~~.		# 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.		# 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 ~~along~~ with ~~optimal~~ LED duty ~~cycles~~. ~~The~~ ADS1220 ~~ADC samples at 200 samples/sec and targets~~ the ~~0.5–3.8V sensor range~~. Calibration typically takes 30–60 seconds.		'''Technical detail:''' Calibration determines the per-channel correction factor K = Ref_avg / Sen_avg and stores it with the LED duty cycle values. Current ESP32 builds use ADS1220 block averaging for the optical readings. Calibration typically takes 30–60 seconds.

	=== Data Management ===		=== Data Management ===

	Data is ~~able to be~~ stored on the device's internal storage ~~for about 3 months of continuous sampling every 5 minutes before deleting the oldest log~~. ~~To manage your session files:~~		Data is stored on the device's internal flash storage (LittleFS) and persists across reboots.

	# Click '''Log Files'''.		Click '''Log Files''' to open the data manager. The modal displays a table listing all stored sessions:
	~~# '''Logs (>2 KB):''' Valid measurement~~ sessions~~. Download these for analysis.~~
	~~# '''Logs (<2 KB)~~:~~''' Failed starts or very short tests — can typically be deleted.~~

	~~Downloads available~~ as CSV (for analysis), PNG, or SVG ~~(for printing)~~. CSV files use semicolon separation with dot as decimal divider.		{\| class="wikitable"
			! Column !! Description
			\|-
			\| '''Log''' \|\| Session name or filename (e.g., <code>bcmeter_20260312_2126.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.		'''Backup:''' Internal storage is not archival. Download data to a secure location regularly.

			'''Storage management:''' The device has ~2 MB internal flash for logs. Warning at 512 KB free, critical at 32 KB. Old logs are auto-deleted when critical threshold is reached. Empty files are cleaned on startup.

	=== Device Management ===		=== Device Management ===
Line 52:		Line 65:

	* '''Calibrate Device:''' Adjusts LED duty cycles. Required after each filter change.		* '''Calibrate Device:''' Adjusts LED duty cycles. Required after each filter change.
	* '''View System ~~Logs~~:''' Opens ~~the application log~~ for diagnosing issues. ~~Logs~~ are grouped by category: hardware, measurement, system, network.		* '''View System Status:''' Opens a structured status report for diagnosing issues. Entries are grouped by category: hardware, measurement, system, network.
	* '''Download Logs:''' Downloads system ~~log~~ for troubleshooting or support.		* '''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 correct physical device when multiple bcMeters are nearby.

	==== System Operations ====		==== System Operations ====
Line 59:		Line 73:
	* '''Reboot Device:''' Restarts the device.		* '''Reboot Device:''' Restarts the device.
	* '''Shutdown Device:''' Safely powers off to prevent data corruption. Always use this before unplugging. If the device loses power during a session without proper shutdown, it will automatically resume measurement on next boot.		* '''Shutdown Device:''' Safely powers off to prevent data corruption. Always use this before unplugging. If the device loses power during a session without proper shutdown, it will automatically resume measurement on next boot.
	* '''Update ~~Firmware~~:''' Opens a dialog to manually upload a firmware file (.~~tar.gz or .zip~~). The device also checks for updates automatically ~~several~~ times a day ~~and notifies you when one is available~~.		* '''Manual Firmware Update:''' Opens a dialog to manually upload a firmware file (.bin). The device also checks for updates automatically 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.		* '''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 ===		=== System Status ===
Line 66:		Line 90:
	Displays device information:		Displays device information:

	* '''Device ID:''' Unique hardware identifier.		* '''Device ID:''' Unique hardware identifier (MAC address).
	* '''Device Name:''' Current network hostname.
	* '''Software Version:''' Installed firmware version.		* '''Software Version:''' Installed firmware version.
	* '''Free Memory:''' Available system memory.		* '''Free Memory:''' Available system memory.
Line 79:		Line 102:
	* '''Sync:''' If mismatch exceeds 10 seconds, a sync button appears to synchronize the device clock with your browser.		* '''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 ~~''(optional — requires 4G module)''~~.		Devices connected to the internet sync automatically via NTP. Modem-based time sync (CLTS) is also supported when a 4G modem is connected.

	=== Geolocation ===		=== Geolocation ===

	When location services are active (Settings > Measurement > Location), a Geolocation card displays ~~position and altitude data. ''The available fields depend on which optional hardware modules are installed.''~~		When location services are active (Settings > Measurement > Location), a Geolocation card displays:

	* '''Location:''' Latitude/longitude with source ~~and accuracy indicator. Sources vary by hardware:~~ GPS ~~module ''(optional)''~~, ~~cellular modem~~ cell tower ~~lookup ''(optional, requires 4G module)''~~, or IP-based ~~geolocation (available on all WiFi-connected devices~~).		* '''Location:''' Latitude/longitude with source (GPS, cell tower, or IP-based) and accuracy indicator.
	* '''Altitude (barometric):''' Derived from the pressure sensor. ~~''Optional — requires a BME280 pressure sensor.''~~		* '''Altitude (barometric):''' Derived from the pressure sensor.
	* '''Altitude (GPS) & Speed:''' ~~GPS-derived altitude and current speed. ''Optional — only shown~~ when a GPS module is ~~installed~~ and has a ~~satellite~~ fix.''		* '''Altitude (GPS) & Speed:''' Shown when a GPS module is connected and has a fix.

	The location input supports multiple formats: <code>48.2082, 16.3738</code> — <code>48.2082 16.3738</code> — <code>(48.2082; 16.3738)</code> etc.		The location input supports multiple formats: <code>48.2082, 16.3738</code> — <code>48.2082 16.3738</code> — <code>(48.2082; 16.3738)</code> etc.

Bcmwiki: Sync with updated manual: updated calibration description, updated data management (3 months storage, oldest log deletion), updated filter change procedure (check for residue), updated firmware upload formats

2026-03-31T18:18:30Z

Sync with updated manual: updated calibration description, updated data management (3 months storage, oldest log deletion), updated filter change procedure (check for residue), updated firmware upload formats

← Older revision		Revision as of 18:18, 31 March 2026
Line 1:		Line 1:
	== Maintenance Procedures ==		== Maintenance Procedures ==

	Access maintenance functions via the '''Maintenance''' button ~~(wrench icon)~~ in the navigation bar. The modal is organized into cards for device management, system status, time synchronization, and geolocation.		Access maintenance functions via the '''Maintenance''' button in the navigation bar. The modal is organized into cards for device management, system status, time synchronization, and geolocation.

	=== Filter Change Procedure ===		=== Filter Change Procedure ===
Line 10:		Line 10:
	* The '''marked side must face UP''' (towards the LEDs/light source in the upper optical chamber).		* 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.		'''Warning:''' Incorrect orientation (marked side down) results in ~30% measurement error. Do not bend or fold the filter. Creases damage the filter surface and cause unreliable measurements.

	'''Procedure:'''		'''Procedure:'''

	# Stop ~~any~~ running session.		# Stop running session.
	# Unscrew the top cap of the optical chamber.		# Unscrew the top cap of the optical chamber.
	# Remove the saturated filter.		# Remove the saturated filter.
			# Check the air inlet for filter paper residue and '''remove if present'''.
	# Insert a new filter with '''markings facing up'''.		# Insert a new filter with '''markings facing up'''.
	# Screw the cap back on (hand-tight).		# Screw the cap back on (hand-tight).
Line 24:		Line 25:
	=== Calibration ===		=== Calibration ===

	~~Filters vary slightly in optical density.~~ Calibration balances the sensor signal against the reference signal for the specific filter currently installed.		Calibration balances the sensor signal against the reference signal for the specific filter currently installed and should ideally be processed on every filter change — although the calibration factor will change extremely slowly once determined.

	# Go to '''Maintenance''' > '''Calibrate Device'''.		# Go to '''Maintenance''' > '''Calibrate Device'''.
Line 36:		Line 37:
	=== Data Management ===		=== Data Management ===

	Data is stored on the device's internal storage ~~(with SD card as optional backup)~~.		Data is able to be stored on the device's internal storage for about 3 months of continuous sampling every 5 minutes before deleting the oldest log. To manage your session files:

	# Click '''Log Files'''.		# Click '''Log Files'''.
Line 45:		Line 46:

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

	'''Storage management:''' The device has ~2 MB internal flash for logs. Warning at 512 KB free, critical at 32 KB. Old logs are auto-deleted when critical threshold is reached. Empty files are cleaned on startup.

	=== Device Management ===		=== Device Management ===
Line 54:		Line 53:
	* '''Calibrate Device:''' Adjusts LED duty cycles. Required after each filter change.		* '''Calibrate Device:''' Adjusts LED duty cycles. Required after each filter change.
	* '''View System Logs:''' Opens the application log for diagnosing issues. Logs are grouped by category: hardware, measurement, system, network.		* '''View System Logs:''' Opens the application log for diagnosing issues. Logs are grouped by category: hardware, measurement, system, network.
	* '''Download Logs:''' Downloads ~~full~~ system ~~logs~~ for troubleshooting or support.		* '''Download Logs:''' Downloads system log for troubleshooting or support.

	==== System Operations ====		==== System Operations ====
Line 60:		Line 59:
	* '''Reboot Device:''' Restarts the device.		* '''Reboot Device:''' Restarts the device.
	* '''Shutdown Device:''' Safely powers off to prevent data corruption. Always use this before unplugging. If the device loses power during a session without proper shutdown, it will automatically resume measurement on next boot.		* '''Shutdown Device:''' Safely powers off to prevent data corruption. Always use this before unplugging. If the device loses power during a session without proper shutdown, it will automatically resume measurement on next boot.
	* '''Update Firmware:''' Opens a dialog to manually upload a firmware file (.tar.gz). The device also checks for updates automatically ~~every 6 hours~~ and notifies you when one is available.		* '''Update Firmware:''' Opens a dialog to manually upload a firmware file (.tar.gz or .zip). The device also checks for updates automatically several times a day and notifies you when one is available.
	* '''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.		* '''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.

Line 67:		Line 66:
	Displays device information:		Displays device information:

	* '''Device ID:''' Unique hardware identifier ~~(MAC address)~~.		* '''Device ID:''' Unique hardware identifier.
	* '''Device Name:''' Current network hostname.		* '''Device Name:''' Current network hostname.
	* '''Software Version:''' Installed firmware version.		* '''Software Version:''' Installed firmware version.

Bcmwiki: Move Identify Device to Developer mode page (dev setting)

2026-03-26T14:22:46Z

Move Identify Device to Developer mode page (dev setting)

← Older revision		Revision as of 14:22, 26 March 2026
Line 55:		Line 55:
	* '''View System Logs:''' Opens the application log for diagnosing issues. Logs are grouped by category: hardware, measurement, system, network.		* '''View System Logs:''' Opens the application log for diagnosing issues. Logs are grouped by category: hardware, measurement, system, network.
	* '''Download Logs:''' Downloads full system logs for troubleshooting or support.		* '''Download Logs:''' Downloads full system logs for troubleshooting or support.
	* '''Identify Device:''' Blinks the device LED in a distinctive pattern for 30 seconds, helping you visually locate a specific device when multiple units are deployed.

	==== System Operations ====		==== System Operations ====

Bcmwiki: Add Identify Device button; mark GPS, 4G, pressure sensor as optional hardware

2026-03-26T12:31:52Z

Add Identify Device button; mark GPS, 4G, pressure sensor as optional hardware

← Older revision		Revision as of 12:31, 26 March 2026
Line 55:		Line 55:
	* '''View System Logs:''' Opens the application log for diagnosing issues. Logs are grouped by category: hardware, measurement, system, network.		* '''View System Logs:''' Opens the application log for diagnosing issues. Logs are grouped by category: hardware, measurement, system, network.
	* '''Download Logs:''' Downloads full system logs for troubleshooting or support.		* '''Download Logs:''' Downloads full system logs for troubleshooting or support.
			* '''Identify Device:''' Blinks the device LED in a distinctive pattern for 30 seconds, helping you visually locate a specific device when multiple units are deployed.

	==== System Operations ====		==== System Operations ====
Line 80:		Line 81:
	* '''Sync:''' If mismatch exceeds 10 seconds, a sync button appears to synchronize the device clock with your browser.		* '''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.		Devices connected to the internet sync automatically via NTP. Modem-based time sync (CLTS) is also supported when a 4G modem is connected ''(optional — requires 4G module)''.

	=== Geolocation ===		=== Geolocation ===

	When location services are active (Settings > Measurement > Location), a Geolocation card displays:		When location services are active (Settings > Measurement > Location), a Geolocation card displays position and altitude data. ''The available fields depend on which optional hardware modules are installed.''

	* '''Location:''' Latitude/longitude with source (~~GPS~~, cell tower, or IP-based) ~~and accuracy indicator~~.		* '''Location:''' Latitude/longitude with source and accuracy indicator. Sources vary by hardware: GPS module ''(optional)'', cellular modem cell tower lookup ''(optional, requires 4G module)'', or IP-based geolocation (available on all WiFi-connected devices).
	* '''Altitude (barometric):''' Derived from the pressure sensor.		* '''Altitude (barometric):''' Derived from the pressure sensor. ''Optional — requires a BME280 pressure sensor.''
	* '''Altitude (GPS) & Speed:''' ~~Shown~~ when a GPS module is ~~connected~~ and has a fix.		* '''Altitude (GPS) & Speed:''' GPS-derived altitude and current speed. ''Optional — only shown when a GPS module is installed and has a satellite fix.''

	The location input supports multiple formats: <code>48.2082, 16.3738</code> — <code>48.2082 16.3738</code> — <code>(48.2082; 16.3738)</code> etc.		The location input supports multiple formats: <code>48.2082, 16.3738</code> — <code>48.2082 16.3738</code> — <code>(48.2082; 16.3738)</code> etc.

Bcmwiki: Update: V1/V2 naming, remove ESP32/Pi distinction

2026-03-08T13:21:11Z

Update: V1/V2 naming, remove ESP32/Pi distinction

← Older revision		Revision as of 13:21, 8 March 2026
Line 32:		Line 32:
	# Wait for "Calibration Successful" before starting a new log.		# 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 along with optimal LED duty cycles. ~~On the ESP32, this uses the~~ ADS1220 ADC ~~with~~ 200 samples/sec and targets the 0.5–3.8V sensor range. Calibration typically takes 30–60 seconds.		'''Technical detail:''' Calibration determines the per-channel correction factor K = Ref_avg / Sen_avg and stores it along with optimal LED duty cycles. The ADS1220 ADC samples at 200 samples/sec and targets the 0.5–3.8V sensor range. Calibration typically takes 30–60 seconds.

	=== Data Management ===		=== Data Management ===

	Data is stored on the device's internal storage (~~LittleFS on ESP32,~~ SD card as optional backup).		Data is stored on the device's internal storage (with SD card as optional backup).

	# Click '''Log Files'''.		# Click '''Log Files'''.
Line 46:		Line 46:
	'''Backup:''' Internal storage is not archival. Download data to a secure location regularly.		'''Backup:''' Internal storage is not archival. Download data to a secure location regularly.

	'''Storage management:''' The ~~ESP32~~ has ~2 MB internal flash for logs. Warning at 512 KB free, critical at 32 KB. Old logs are auto-deleted when critical threshold is reached. Empty files are cleaned on startup.		'''Storage management:''' The device has ~2 MB internal flash for logs. Warning at 512 KB free, critical at 32 KB. Old logs are auto-deleted when critical threshold is reached. Empty files are cleaned on startup.

	=== Device Management ===		=== Device Management ===
Line 80:		Line 80:
	* '''Sync:''' If mismatch exceeds 10 seconds, a sync button appears to synchronize the device clock with your browser.		* '''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. ~~The ESP32 also supports modem~~-based time sync (CLTS) when a 4G modem is connected.		Devices connected to the internet sync automatically via NTP. Modem-based time sync (CLTS) is also supported when a 4G modem is connected.

	=== Geolocation ===		=== Geolocation ===

Bcmwiki: Wiki update: sync with manual and dev docs (2026-03)

2026-03-08T13:10:43Z

Wiki update: sync with manual and dev docs (2026-03)

New page

== Maintenance Procedures ==

Access maintenance functions via the '''Maintenance''' button (wrench icon) in the navigation bar. The modal is organized into 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): ensure the air hose remains 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'''.
# Ensure a '''new and clean filter''' is installed.
# Click "Yes."
# A progress bar appears. The device adjusts LED intensity per channel using binary search to find optimal duty cycles.
# 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 along with optimal LED duty cycles. On the ESP32, this uses the ADS1220 ADC with 200 samples/sec and targets the 0.5–3.8V sensor range. Calibration typically takes 30–60 seconds.

=== Data Management ===

Data is stored on the device's internal storage (LittleFS on ESP32, SD card as optional backup).

# Click '''Log Files'''.
# '''Logs (>2 KB):''' Valid measurement sessions. Download these for analysis.
# '''Logs (<2 KB):''' Failed starts or very short tests — can typically be deleted.

Downloads available as CSV (for analysis), PNG, or SVG (for printing). CSV files use semicolon separation with dot as decimal divider.

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

'''Storage management:''' The ESP32 has ~2 MB internal flash for logs. Warning at 512 KB free, critical at 32 KB. Old logs are auto-deleted when critical threshold is reached. Empty files are cleaned on startup.

=== Device Management ===

==== Routine Maintenance ====

* '''Calibrate Device:''' Adjusts LED duty cycles. Required after each filter change.
* '''View System Logs:''' Opens the application log for diagnosing issues. Logs are grouped by category: hardware, measurement, system, network.
* '''Download Logs:''' Downloads full system logs for troubleshooting or support.

==== System Operations ====

* '''Reboot Device:''' Restarts the device.
* '''Shutdown Device:''' Safely powers off to prevent data corruption. Always use this before unplugging. If the device loses power during a session without proper shutdown, it will automatically resume measurement on next boot.
* '''Update Firmware:''' Opens a dialog to manually upload a firmware file (.tar.gz). The device also checks for updates automatically every 6 hours and notifies you when one is available.
* '''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.

=== System Status ===

Displays device information:

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

=== Time Synchronization ===

Critical for accurate data timestamps, especially for devices without internet.

* '''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. The ESP32 also supports modem-based time sync (CLTS) when a 4G modem is connected.

=== Geolocation ===

When location services are active (Settings > Measurement > Location), a Geolocation card displays:

* '''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 supports multiple formats: <code>48.2082, 16.3738</code> — <code>48.2082 16.3738</code> — <code>(48.2082; 16.3738)</code> etc.