Two ways to build Air360
You can assemble the device with the Air360 shield board or wire sensors directly to the ESP32-S3. The shield reduces wiring mistakes; direct wiring is useful for prototypes, debugging, and custom enclosures.
Build with the shield board
The shield breaks power and signal lines out to labeled connectors. This is the primary user path for repeatable builds.
- Order the board from Gerber files or from the OSHWLab project.
- Check the board revision against this guide before soldering.
- After assembly, sensors connect to the labeled shield connectors.
Wire directly to ESP32-S3
Connect sensors to GPIOs directly using the table below. This path requires careful power, ground, and shared-bus wiring.
- For multiple I2C devices, use a branched I2C bus or a dedicated hub.
- Search for "I2C hub" on AliExpress, Amazon, or similar marketplaces.
- All signal lines must be compatible with ESP32-S3 3.3 V logic.
- UART1 is shared by GPS and the cellular modem by default, so use separate UART ports if both are installed.
Option 1: build with the shield board
The shield board sits on top of the ESP32-S3 and breaks power, I2C, UART, and auxiliary lines out to connectors. These are the baseline parts needed to assemble the board.
| Component | Qty | Use | Search keywords |
|---|---|---|---|
| DS1023-1x22S21, 1x22 female socket header, 2.54 mm pitch | 2 pcs | Headers for mounting the shield board onto the ESP32-S3. | DS1023-1x22S21 female header 2.54mm |
| Single row male 2.54 mm breakable pin header | 1 strip or as needed | Male pin headers for auxiliary pins and jumpers. | 2.54mm single row breakable male pin header |
| DC-005, 5.5x2.1 mm PCB-mount DC barrel jack | 1 pc | DC power input on the shield board. | DC-005 5.5x2.1mm PCB mount DC power jack |
| JST ZH 1.5 mm, 4-pin / 5-pin connector set | as needed | Optional cable connectors for SPS30 and SCD30. | JST ZH 1.5mm 4 pin 5 pin connector housing crimp terminal |
| KF301-5.0-2P, 2-pin 5.0 mm screw terminal block | 1 pc if INA219 is used | Screw terminal for the INA219 power measurement path. | KF301-5.0-2P 2 pin 5.0mm screw terminal block |
| 0 Ω resistor / 0R jumper | 1 pc if INA219 is not used | Jumper in place of the INA219 path when current sensing is not installed. | 0 ohm resistor 0R jumper |
Option 2: direct wiring to ESP32-S3
The table below follows the current firmware defaults. Some UART and GPIO sensors can be reassigned in the device web UI, but these values are the best starting point for a first build.
- I2C: all I2C sensors share SDA=GPIO8 and SCL=GPIO9.
- GPIO and analog sensors use one of GPIO4, GPIO5, or GPIO6.
| Sensor | Interface | ESP32-S3 pins | Note |
|---|---|---|---|
| I2C | SDA=GPIO8, SCL=GPIO9 | Use one shared I2C bus for multiple modules; sensor addresses must not conflict. |
| UART2 by default, 9600 baud | RX=GPIO16, TX=GPIO15; UART1 RX=GPIO18, TX=GPIO17 is selectable | Sensor TX goes to ESP32-S3 RX; sensor RX goes to ESP32-S3 TX. |
| UART1 by default, 9600 baud | RX=GPIO18, TX=GPIO17; UART2 RX=GPIO16, TX=GPIO15 is selectable | UART1 conflicts with the SIM7600E default pins. |
| GPIO | GPIO4, GPIO5, or GPIO6 | Select one available pin in the sensor settings. |
| GPIO | P1/yellow signal to GPIO4 by default; GPIO5 or GPIO6 selectable | Requires 3.3 V-safe signal level shifting. |
| UART1, 115200 baud | RX=GPIO18, TX=GPIO17, PWRKEY=GPIO12, SLEEP/DTR=GPIO21 | RESET is not wired by default; do not use GPS on UART1 at the same time. |
Flashing the device
The easiest way to start is to flash the ready-made merged full.bin image with the browser-based ESP Flash tool. After first boot, the device starts a Wi-Fi setup access point.
Flash, connect to setup AP, then open the device in a browser
Access point name after a clean flash.
Default setup access point password.
Open the device web interface by hostname or by IP address.
Download full.bin
Open the Air360 releases and download the current full.bin file. This is the complete image for first-time device flashing.
Connect ESP32-S3 by USB
Open espflash.app, select the board serial port, and choose the downloaded full.bin. If the port is missing, check the cable and the board boot mode.
Start flashing
Write the image and wait for the device to reboot. After a clean flash, the device starts setup AP mode with SSID air360.
Configure Wi-Fi
Connect to air360 with password air360password, open http://192.168.4.1/config, and save your network SSID and password.
Verify startup
After the device joins your network, open http://air360.local/ or the device IP address from your router and check the Overview page.
Continue setup
After flashing, configure sensors and backend uploads in the device web interface.
Detailed documentation
For web UI setup, sensors, backend uploads, diagnostics, and OTA, use the full firmware user guide.
Enclosure: Stevenson screen
For outdoor installation, you can 3D-print a Stevenson-screen-style enclosure. It shields the device from direct sun and rain while keeping airflow around the sensors.
Sensor.Community compatibility
Air360 firmware keeps backward compatibility with Sensor.Community: the device can still upload to the legacy Sensor.Community endpoint using the same short device ID registered on devices.sensor.community. Air360 API is broader and accepts every current sensor type.
| Sensor / group | Sensor.Community | Air360 API |
|---|---|---|
| BME280, BME680 | Yes: temperature, humidity, pressure; gas resistance is skipped | Yes: all sensor values in a typed JSON batch |
| DHT11, DHT22, HTU2X, SHT3X, SHT4X | Yes: temperature and humidity | Yes: all sensor values |
| DS18B20 | Yes: temperature | Yes |
| SCD30 | Yes: temperature, humidity, CO2 | Yes |
| SPS30 | Yes: PM1.0, PM2.5, PM4.0, PM10, number concentration bins, typical particle size | Yes |
| SDS011 | Yes: PM2.5 and PM10 | Yes |
| PMSX003 | Partial: PM1.0, PM2.5, PM10; particle-count bins are skipped | Yes: PM and particle-count values |
| GPS (NMEA) | Partial: latitude, longitude, altitude; satellites/speed/course/HDOP are skipped | Yes: all GPS values |
| AHT30, VEML7700, OPT3001, PPD42NS, INA219, MH-Z19B | No: the Sensor.Community adapter skips these types | Yes: all values pass through without sensor-type filtering |
What makes Air360 firmware different
The firmware keeps the Sensor.Community flow working, but adds capabilities that do not fit the older upload format.
Sensor.Community stays available
You can still register the device on devices.sensor.community and upload compatible measurements to their API.
Air360 API accepts every sensor
The native backend receives one typed JSON batch with sensor_type, kind, and timestamp, including values that have no legacy Sensor.Community mapping.
Cellular modem out of the box
SIM7600 and other esp-modem types are managed by a dedicated cellular runtime: PPP, reconnect backoff, PWRKEY/SLEEP GPIO, and diagnostics in the web UI.
Power and extended sensors
INA219, VEML7700/OPT3001, PPD42NS, MH-Z19B, and other sensors are available in firmware and Air360 API even when Sensor.Community does not accept them.
Local web UI
Wi-Fi, cellular, sensor configuration, upload backends, OTA, and diagnostics are available through the device web interface.
Multiple backend uploads
In addition to Sensor.Community, the firmware supports Air360 API, Custom Upload, and InfluxDB, each with separate configuration and delivery status.