Difference between revisions of "Setup"

Latest revision as of 22:15, 2 May 2026

Setup & Initialization

Hardware Requirements

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

ESP32 bcMeter V2: use a suitable 12V / 2A power adapter.
Raspberry Pi based development devices: use a suitable 5V / 2.5A power adapter.
Use a short, low-resistance cable (ideally under 40 cm). Long or thin cables can drop enough voltage to reboot the device when the pump starts.

Initial Device Setup

Before starting measurements:

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

Connecting via Hotspot

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

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

The Welcome Screen will appear on first use.

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

Welcome Screen

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

Phase 1: Connect

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

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

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

Phase 2: Calibrate & Share

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

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

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

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

Important: Run calibration after setup.

Connecting to Wireless Network

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

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

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

Accessing the Interface

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

Standard device: http://bcmeter-A3AB.local
Emission control version: http://ebcmeter-A3AB.local

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

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

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

Connection Lost

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

@@ Line 3: / Line 3: @@
 === Hardware Requirements ===
-'''Power Supply is Critical:''' The most common cause of instability (wireless disconnects, random reboots) is an inadequate power supply.
+'''Use a stable power supply:''' Weak adapters and voltage drops are the most common causes of WiFi dropouts and random reboots.
-* Use a high-quality '''5V / 2.5A''' power adapter.
+* ESP32 bcMeter V2: use a suitable '''12V / 2A''' power adapter.
-* Use a '''short, high-quality USB cable''' (ideally under 40 cm). Long or thin cables cause voltage drops that can crash the device when the pump starts.
+* Raspberry Pi based development devices: use a suitable '''5V / 2.5A''' power adapter.
+* Use a '''short, low-resistance cable''' (ideally under 40 cm). Long or thin cables can drop enough voltage to reboot the device when the pump starts.
 === Initial Device Setup ===
@@ Line 14: / Line 15: @@
 # Place the device '''away from direct heat sources and sunlight''' (thermal drift affects optical measurements).
 # Insert a fresh filter paper ('''marked side facing up''' — see [[Maintenance#Filter Change Procedure|Filter Change Procedure]]).
-# If using a rugged case: ensure the hose from bcMeter to the environment is firmly inserted and free of obstructions.
+# If using a rugged case: check that the hose from bcMeter to the outside air is firmly inserted and not blocked.
 === Connecting via Hotspot ===
@@ Line 21: / Line 22: @@
 # Plug in the device.
-# Wait approximately '''2 minutes''' for the system to boot.
+# Wait '''1-2 minutes''' for the system to boot.
-# On your phone or computer, search for a WiFi network named '''bcMeter''' or '''eBcMeter'''.
+# On your phone or computer, search for a WiFi network whose name starts with '''bcMeter''' or '''eBcMeter'''.
-# Connect using the password: <code>bcMeterbcMeter</code> (case sensitive).
+# If asked, connect using the password <code>bcMeterbcMeter</code> (case sensitive). Recent ESP32 devices may create an open setup hotspot and will not ask for a password.
 # Your phone may warn "No Internet Connection." '''This is normal.''' Select "Keep Connected" if prompted. Do not choose "use mobile data."
-# Open a browser and type <code><nowiki>http://bcmeter.local</nowiki></code> or <code><nowiki>http://192.168.18.8</nowiki></code>.
+# Open a browser and type <code><nowiki>http://bcmeter-XXXX.local</nowiki></code> (where XXXX are the last 4 hex characters of the MAC address, e.g. <code>bcmeter-A3AB</code>) or <code><nowiki>http://192.168.18.8</nowiki></code>.
 The '''[[Setup#Welcome Screen|Welcome Screen]]''' will appear on first use.
@@ Line 33: / Line 34: @@
 === Welcome Screen ===
-On first use, bcMeter shows a welcome screen that guides you through three steps:
+On first use, bcMeter shows a two-phase welcome screen for network setup, calibration, and data sharing.
-# '''Install a clean filter''' — Place a fresh quartz filter in the holder.
+==== Phase 1: Connect ====
-# '''Calibrate''' — Perform a baseline reading with the clean filter. You can open calibration directly from here.
-# '''Get connected''' — Enter your email address and select your WiFi network. bcMeter will send you the interface link after connecting, and deliver daily measurement reports to this address.
-Select your WiFi network from the dropdown and enter the WiFi key. Optionally enable or disable daily measurement reports and data sharing.
+The first screen ("Connect this bcMeter") covers connectivity:
-Click '''Get Started''' to save settings and connect to WiFi. The device hotspot will turn off and bcMeter joins your network. Check your email for the interface link.
+* '''Notification email''' — Enter the address where bcMeter should send status messages and alerts. After WiFi setup, the device can send its URL and connection details to this address.
+* '''Enable email notifications''' — Toggle to receive status updates and measurement reports.
+* '''Connect to network''' — Select your network from the dropdown, click '''Scan''' to refresh, or choose '''Enter manually''' for hidden networks. Enter the WiFi password and click '''Connect'''.
-'''Tip:''' You can skip the welcome screen and configure everything later in Settings. It will appear again until you complete setup or choose "Don't show again."
+The email step offers "Skip for now" and "Don't show again". The WiFi step offers "Back" and "Skip".
-'''Important:''' Run [[Maintenance#Calibration|calibration]] after successful configuration.
+==== Phase 2: Calibrate & Share ====
+After connecting to WiFi (or if WiFi was already configured), the second screen ("Almost there") appears:
+* '''Install a clean filter''' — Place a fresh quartz filter in the holder.
+* '''Calibrate''' — Perform a baseline reading. Click "Start calibration →" to open the calibration dialog directly.
+* '''Data sharing''' — Shared measurements help build the bcMeter black carbon map. You can choose:
+** '''Get Started & Share Data''' — Enables anonymous data sharing for the project.
+** '''Get Started without Sharing''' — Proceeds without sharing. You can change this later in Settings.
+The calibration/sharing phase has "Skip for now" and "Don't show again" options at the bottom.
+'''Tip:''' The welcome screen will reappear on each visit until setup is complete or you choose "Don't show again."
+'''Important:''' Run [[Maintenance#Calibration|calibration]] after setup.
 === Connecting to Wireless Network ===
@@ Line 52: / Line 67: @@
 # Navigate to '''Settings''' > '''Network''' tab.
-# Select your network from the list. For hidden networks, check "Connect to hidden network" and type the SSID manually.
+# Select your network from the list. For hidden networks, choose "Enter manually" and type the SSID yourself.
-# Enter your WiFi key and click '''Save & Connect'''.
+# Enter your WiFi key and click '''Connect'''.
-# The device will disconnect from you. Reconnect your computer to your home WiFi.
+# The setup hotspot disconnects while the device joins the selected network. Reconnect your computer to your normal WiFi.
 # Wait 1–2 minutes for the device to join your network.
@@ Line 61: / Line 76: @@
 === Accessing the Interface ===
-Once on your home network, access the device using its hostname:
+When the device is on your network, open it by hostname. The default hostname follows the pattern <code>bcmeter-XXXX</code> (or <code>ebcmeter-XXXX</code> for emission devices), where XXXX are the last 4 hex characters of the device's MAC address. For example:
+* Standard device: <code><nowiki>http://bcmeter-A3AB.local</nowiki></code>
+* Emission control version: <code><nowiki>http://ebcmeter-A3AB.local</nowiki></code>
-* Standard device: <code><nowiki>http://bcmeter.local</nowiki></code>
+The exact hostname is shown on the device label and in the Welcome screen email. You can rename the device in Settings > Device > Device Name.
-* Emission control version: <code><nowiki>http://ebcmeter.local</nowiki></code>
 '''Tip:''' If <code>.local</code> addresses do not work (common on some Windows networks or older routers), find the device's IP address in your router's administration interface.
-'''Browser Security Warnings:''' The bcMeter web server uses HTTP (not HTTPS), which triggers browser warnings. This is expected — the device runs locally on your network with no public internet connection. You must explicitly allow access to <code>bcmeter.local</code>. On macOS, you may also need to grant permission for your browser to access LAN devices.
+'''Browser Security Warnings:''' The bcMeter web server uses HTTP (not HTTPS), which triggers browser warnings. This is expected — the device runs locally on your network with no public internet connection. You must explicitly allow access to the device's <code>.local</code> address. On macOS, you may also need to grant permission for your browser to access LAN devices.
+=== Connection Lost ===
+If the browser loses contact with the device (for example during a reboot or network drop), a "Connection Lost" overlay appears. The interface keeps trying to reconnect until the device is reachable again.