User Guide

CrowdPM — User Guide

Live site: https://crowdpmplatform.web.app/

CrowdPM is a community-powered air quality platform. Anyone can visit the map and explore real-time PM2.5 sensor data contributed by people in the community. If you own a CrowdPM sensor node, you can also create an account, pair your device, and start contributing your own measurements.

---

Table of Contents

1. Getting Around the App
2. The Live Map
3. Creating an Account
4. Logging In and Out
5. User Dashboard
6. Pairing a Sensor Node
7. Managing Your Batches
8. Video Export
9. User Settings
10. Pages Reference
11. Frequently Asked Questions

---

1. Getting Around the App

The Header

A branded header bar is always visible across every page. Clicking the CrowdPM logo on the left returns you to the map from anywhere in the app.

The Hamburger Menu (☰)

Below the header on the left side is the navigation menu button (three horizontal lines). Click it to open a dropdown with links to every section of the app:

Menu Item	What it does
Map	Returns to the live 3D air quality map
Pairing Guide	Step-by-step guide for connecting a sensor node
Node Hardware	Hardware build and firmware info
About	Project background and mission
Dashboard	Your personal device and batch manager (sign-in required)
Log in / Sign up	Opens the authentication dialog
Sign out	Signs you out of your account
Team	Meet the people behind CrowdPM

---

2. The Live Map

The map is the first thing you see when you visit the site. It shows PM2.5 air quality measurements from community sensor nodes rendered as a 3D visualization on top of a Google Map.

Browsing Public Data

You don't need an account to explore public data.

1. Open the Measurement batch dropdown in the top-right floating panel.
2. Select "Show all public (last 24h)" to load all publicly shared measurements from the past 24 hours across every node.
3. Color-coded points appear on the map. Click any point to jump to that specific batch and measurement.

Selecting a Specific Batch

A batch is a single recording session from one sensor node — a collection of GPS-tagged PM2.5 readings taken during one outing or deployment.

1. Open the Measurement batch dropdown.
2. Choose any batch from the list. Each entry shows the date/time, the device name, and the number of measurements.
3. The map zooms and tilts to frame the selected batch automatically.

The Timeline Slider

When a specific batch is selected, a Timeline slider appears in the floating panel.

• Drag the slider left or right to step through each measurement in the batch chronologically.
• The currently highlighted point on the map moves to match your slider position.
• Below the slider you can see the exact timestamp, PM2.5 value, GPS coordinates, and precision for the selected point.

The Stats Strip

A small strip at the bottom-left of the map shows a summary of what is currently loaded:

• A pulsing dot indicates live data is present.
• The count of measurements (and batches, in "show all" mode) is displayed.

Welcome Hero (Empty State)

If no batch is selected and no data is loaded, a welcome overlay appears in the centre of the map with two quick actions:

• Browse public data — loads all public measurements from the last 24 hours.
• Pair a node — opens the Pairing Guide in a new tab.

---

3. Creating an Account

An account is required to pair sensor nodes, manage batches, and access your personal dashboard.

1. Open the hamburger menu (☰).
2. Select Sign up.
3. Enter your email address and choose a password (at least 6 characters).
4. Confirm your password and click Create account.

You are signed in automatically after signing up.

---

4. Logging In and Out

To log in:

1. Open the hamburger menu (☰) and select Log in.
2. Enter your email and password, then click Log in.

To log out:

1. Open the hamburger menu (☰).
2. Select Sign out.

Your last-selected batch and cached data are stored per-account in your browser, so your session picks up where you left off when you sign back in.

---

5. User Dashboard

URL: Accessible via the hamburger menu → Dashboard

The dashboard is your control centre for devices and uploaded data. Sign-in is required.

Overview Cards

At the top of the dashboard you'll see:

• Owned devices — total number of nodes linked to your account.
• Active — how many of those nodes currently have a green "Active" status.

Click Refresh to pull the latest data from the server.

Add a Device

Use the Open activation UI button to launch the pairing dialog directly from the dashboard. See Pairing a Sensor Node for the full walkthrough.

---

6. Pairing a Sensor Node

URL: /pairing-guide or via the hamburger menu → Pairing Guide

Pairing connects a physical CrowdPM sensor node to your account. It only needs to be done once per device.

What You'll Need

• A CrowdPM-compatible sensor node, powered on and connected to Wi-Fi.
• A CrowdPM account (sign up if you don't have one).
• A web browser on any device (phone, laptop, tablet).

Steps

Step	What to do
1. Power on your node	Plug in the sensor and let it boot. It connects to Wi-Fi and contacts the CrowdPM server automatically.
2. Read the pairing code	The node's display (or serial output) shows a short code, e.g. ABCD-EFGH-J. This code is valid for 15 minutes.
3. Open the Activation page	In CrowdPM, open the hamburger menu → Dashboard → Open activation UI, or go directly to /activate.
4. Enter the code	Type the pairing code from your node into the activation form and click submit. The page shows the device's model, firmware version, and a unique fingerprint for verification.
5. Approve the device	Confirm the details match your hardware and click Authorize device. The node detects approval within seconds and begins streaming data.

Troubleshooting

Problem	Solution
Code expired	Power-cycle the node to generate a fresh code.
Code not appearing on the node	Ensure the node has internet access and the display/LED is working.
"Session not found" error	Check for typos — the code uses capital letters and dashes (e.g. ABCD-EFGH-J).
Still stuck	Ask for help on the CrowdPM Discord.

---

7. Managing Your Batches

The Batch uploads section of the Dashboard shows every measurement session uploaded by your devices.

The Batch Table

Each row in the table shows:

Column	Meaning
Device	The device name (or ID) that uploaded the batch.
Batch	A unique internal identifier for this recording session.
Uploaded	When the batch was processed by the server.
Points	How many individual PM2.5 measurements are in the batch.
Visibility	Public (visible to everyone on the map) or Private (only you can see it).
Moderation	Approved (normal) or Quarantined (flagged by an admin for review).

Filtering by Device

Use the Device filter dropdown above the table to show batches from only one specific device.

Changing Batch Visibility

• Click Make public to share a batch on the community map.
• Click Make private to hide it from public view.

Changes take effect immediately.

Deleting a Batch

Click the red Delete button on any row. You will be asked to confirm before the batch and its data are permanently removed.

---

8. Video Export

When you have a specific batch selected on the map (not "show all public"), a 🎬 Video Export card appears in the floating controls panel.

This feature lets you render a flythrough video of the batch's measurement path.

How to Export

1. Select a batch from the Measurement batch dropdown.
2. Wait for the measurements to load (the timeline slider will appear).
3. Click Render Video in the Video Export card.
4. A progress bar shows the rendering status as the map steps through each measurement point.
5. Once complete, a Download button appears. Click it to save the video as a .webm file (or .mp4 on supported browsers).
6. Click Re-render to create a new export with the current map state.

Requirements

• The batch must have at least 2 measurements.
• Public batches are exportable when signed out; private batches require you to be signed in as the owner.
• Video export requires a browser that supports canvas recording (Chrome or Edge recommended).

---

9. User Settings

Found in the User settings card on the Dashboard.

Default Batch Visibility

Choose whether new batches from your nodes default to Public or Private when they are uploaded.

• Public — measurements appear on the community map for everyone.
• Private — measurements are only visible to you on your own dashboard and map view.

You can always change the visibility of individual batches later from the Batch uploads table.

Map Rendering Mode

A toggle for Interleaved map rendering controls how the 3D sensor data layer blends with the Google Maps base layer.

• On (default) — better visual blending between the data layer and the map.
• Off — better compatibility if you encounter graphics glitches or WebGL errors on your device.

---

10. Pages Reference

Page	URL	Description
Map	/	The live 3D air quality map — the app's home page.
Pairing Guide	/pairing-guide	How to connect a sensor node to your account.
Node Hardware	/node	Hardware build guide and firmware info (coming soon).
About	/about	Project background, mission, and open-source links.
Dashboard	Hamburger menu	Device and batch management (sign-in required).
Activation	/activate	Device pairing form — can be shared with teammates.

---

11. Frequently Asked Questions

Do I need an account to use CrowdPM? No. Anyone can browse the public map and explore community data without signing up. An account is only needed to pair your own sensor node and manage your data.

What is PM2.5? PM2.5 refers to fine particulate matter smaller than 2.5 micrometres in diameter. At elevated concentrations it can affect respiratory health. CrowdPM measures it in µg/m³ (micrograms per cubic metre).

How often does the map update? Batches are uploaded by sensor nodes and become visible on the map once processed by the server. The batch list on the map refreshes automatically every 30 seconds.

Can I share a batch with someone who doesn't have an account? Yes — set the batch to Public from your dashboard. Public batches appear in the "Show all public (last 24h)" view and can be selected by any visitor to the site.

Can I share the activation link with a teammate? Yes. From the Dashboard, copy the activation link and send it to anyone you trust. They can use it to approve a new device pairing on your behalf without needing access to your account credentials.

What does "Quarantined" mean for a batch? A quarantined batch has been flagged by a platform administrator for review — usually because the data looks anomalous. Quarantined batches are not visible on the public map. Contact the team via Discord if you believe this is an error.

Where can I get a CrowdPM sensor node? CrowdPM is an open-source project. Node hardware specifications and build instructions will be available on the Node Hardware page. You can also follow development on GitHub.

Where can I get help or give feedback? Join the community on the CrowdPM Discord or open an issue on GitHub.