The Polverine board is a mikroBUS™ sensor board developed by BlackIoT featuring the Bosch BMV080 particulate matter sensor and the Bosch BME690 gas sensor connected to a ESP32-S3 microcontroller.
This repository contains a firmware that transforms the Polverine board into a complete IoT environmental monitoring solution with web-based configuration, MQTT connectivity, and Home Assistant integration.
- Zero-code setup: No need to hardcode WiFi credentials
- Web-based configuration: Intuitive browser interface for setup
- Automatic fallback: Creates WiFi hotspot if connection fails
- Persistent storage: Credentials stored in NVS flash memory
- Dual sensor support: BME690 + BMV080 integration
- High-frequency sampling: Continuous environmental monitoring
- Data validation: Built-in sensor error detection and reporting
- Sensor dashboard: Live web interface showing real-time values
- Auto-discovery: Automatically publishes MQTT discovery messages to Home Assistant's
homeassistant/topic prefix - Device registration: Creates a unified device "Polverine XXXXXX" with manufacturer, model, and unique identifier
- Rich entities: 15+ sensor entities including environmental, air quality, and system health metrics
- Entity classification: Proper device classes (temperature, humidity, pm25, etc.) with units and icons
- Status monitoring: Device availability topic, sensor health states, and system diagnostics
- Web interface: Complete configuration through browser
- MQTT settings: Broker, authentication, topic customization
- Network management: WiFi scanning, connection monitoring
- Factory reset: Hardware button for configuration reset
| Sensor | Measurement | Unit | Home Assistant Entity |
|---|---|---|---|
| BME690 | Temperature | °C | sensor.polverine_xxxxx_temperature |
| BME690 | Humidity | % | sensor.polverine_xxxxx_humidity |
| BME690 | Pressure | hPa | sensor.polverine_xxxxx_pressure |
| BME690 | IAQ Index | 0-500 | sensor.polverine_xxxxx_iaq |
| BME690 | CO2 Equivalent | ppm | sensor.polverine_xxxxx_co2 |
| BME690 | VOC Equivalent | ppm | sensor.polverine_xxxxx_voc |
| BME690 | Gas Resistance | % | sensor.polverine_xxxxx_gas_percentage |
| BMV080 | PM10 | µg/m³ | sensor.polverine_xxxxx_pm10 |
| BMV080 | PM2.5 | µg/m³ | sensor.polverine_xxxxx_pm25 |
| BMV080 | PM1 | µg/m³ | sensor.polverine_xxxxx_pm1 |
| System | WiFi RSSI | dBm | sensor.polverine_xxxxx_wifi_rssi |
| System | Free Heap | bytes | sensor.polverine_xxxxx_free_heap |
| System | Uptime | seconds | sensor.polverine_xxxxx_uptime |
| System | CPU Temperature | °C | sensor.polverine_xxxxx_cpu_temperature |
- Power on the Polverine device
- Connect to WiFi network:
Polverine-XXXXXX(password:12345678) - Open browser and navigate to:
http://192.168.4.1 - Configure your WiFi and MQTT settings
- Save configuration - device will restart and connect automatically
- Hold BOOT button for 5 seconds to clear all settings
- Device will restart in provisioning mode
Once connected to your network:
- Configuration:
http://[device-ip]/config - Live Dashboard:
http://[device-ip]/dashboard - Device IP shown in router's DHCP table or Home Assistant discovery
- Python 3.7+ (for PlatformIO)
- Git (for version control)
# Clone the repository
git clone <repository-url>cd polverine
# Install PlatformIO CLI
pip install platformio
# Verify installation
pio --version
⚠️ Important: Due to Bosch Sensortec licensing restrictions, SDKs must be downloaded separately after agreeing to their terms.
BMV080 Particulate Matter Sensor SDK v11.2.0
- 🔗 Download:BMV080 SoftwareSDK Download
- 📁 Extract to:
deps/bosch-sensortec/BMV080-SDK/ - ✅ Expected structure:
deps/bosch-sensortec/BMV080-SDK/ ├── api/ ├── api_examples/ ├── CHANGELOG.md ├── LICENSE.md └── README.md
BME690 BSEC Gas Sensor Library v3.2.0
- 🔗 Download:BME690 SoftwareBSEC Download
- 📁 Extract to:
deps/bosch-sensortec/bsec_library_v3.x/ - ✅ Expected structure:
deps/bosch-sensortec/bsec_library_v3.x/ ├── algo/ ├── examples/ └── README.md
The fastest way to get started is using the provided Makefile:
# All-in-one: build, upload, and monitor
make
# Or step by step:
make build # Build firmware only
make upload # Flash to device
make monitor # View serial output| Command | Description | Use Case |
|---|---|---|
make | Build + upload + monitor | Deploy and test |
make build | Compile firmware only | Testing compilation |
make upload | Flash to device | Deploy new build |
make monitor | Start serial monitor | Debug & testing |
make deploy | Build + upload only | Production deployment |
make clean | Remove build files | Fix build issues |
make rebuild | Clean + build | Force complete rebuild |
make help | Show all targets | Reference |
If you prefer direct PlatformIO commands:
# Build for Polverine board
pio run -e polverine
# Upload to connected device
pio run -e polverine -t upload
# Monitor serial output (Ctrl+C to exit)
pio device monitor --baud 115200
# Clean build artifacts
pio run -t cleanThe device creates a WiFi hotspot for first-time setup - no pre-configuration needed!
- Connect to
Polverine-XXXXXXnetwork (password:12345678) - Navigate to
http://192.168.4.1 - Configure WiFi and MQTT settings via web interface
For development convenience, create credentials.ini in the project root:
[credentials]wifi_ssid = "YourWiFiNetwork"wifi_pass = "YourWiFiPassword"mqtt_uri = "mqtt://your-broker.local:1883"mqtt_user = "your-mqtt-username"mqtt_pass = "your-mqtt-password"Note: Build-time credentials are used as defaults but can be overridden via the web interface.
- Documentation:BlackIoT Polverine FAQ
- Hardware Purchase:Mouser Electronics
- BlackIoT Swiss for the Polverine hardware platform and the POLVERINE_HOMEASSISTANT_DEMO example that this firmware is originally based on
- Bosch Sensortec for BME690 and BMV080 sensors
- Espressif for ESP32-S3 microcontroller platform
- Home Assistant community for integration standards