diff --git a/docs/howto-compile.md b/docs/howto-compile.md new file mode 100644 index 0000000..0eeb6d8 --- /dev/null +++ b/docs/howto-compile.md @@ -0,0 +1,90 @@ +# How to compile AirGradient firmware on Arduino IDE + +## Prequisite + +Arduino IDE version 2.x ([download](https://www.arduino.cc/en/software)) + +> For AirGradient model ONE and Open Air, the codebase **WILL NOT** work on the latest major version of arduino-esp32 which is *3.x* . This related to when installing "esp32 by Espressif Systems" in board manager. Instead use version **2.0.17**, please follow the first step carefully. + +## Steps for ESP32C3 based board (ONE and Open Air Model) + +1. Install "esp32 by Espressif Systems" in board manager with version **2.0.17** (Tools ➝ Board ➝ Boards Manager ➝ search for `"espressif"`) + +![board manager](images/esp32-board.png) + +2. Install AirGradient library on library manager using the latest version (Tools ➝ Manage Libraries... ➝ search for `"airgradient"`) + +![Aigradient Library](images/ag-lib.png) + +3. On tools tab, follow settings below + +``` +Board ➝ ESP32C3 Dev Module +USB CDC On Boot ➝ Enabled +CPU Frequency ➝ 160MHz (WiFi) +Core Debug Level ➝ None (or choose as needed) +Erase All Flash Before Sketch Upload ➝ Enabled (or choose as needed) +Flash Frequency ➝ 80MHz +Flash Mode ➝ QIO +Flash Size ➝ 4MB (32Mb) +JTAG Adapter ➝ Disabled +Partition Scheme ➝ Minimal SPIFFS (1.9MB APP with OTA/190KB SPIFFS) +Upload Speed ➝ 921600 +``` + +![Compile Settings](images/settings.png) + +4. Open sketch to compile (File ➝ Examples ➝ AirGradient Air Quality Sensor ➝ OneOpenAir). This sketch for AirGradient ONE and Open Air monitor model +5. Compile + +![compiled esp32](images/compiled.png) + +## Steps for ESP8266 based board (DIY model) + +1. Add esp8266 board by adding http://arduino.esp8266.com/stable/package_esp8266com_index.json into Additional Board Manager URLs field (File ➝ Preferences ➝ Additional boards manager URLs) + +![additional-board](images/additional-board.png) + +2. Install esp8266 board on board manager with version **3.1.2** (Tools ➝ Board ➝ Boards Manager ➝ search for `"esp8266"`) + +![board manager](images/esp8266-board.png) + +3. Install AirGradient library on library manager using the latest version (Tools ➝ Manage Libraries... ➝ search for `"airgradient"`) + +![Aigradient Library](images/ag-lib.png) + +4. On tools tab, set board to `LOLIN(WEMOS) D1 R2 & mini`, and let other settings to default + +![settings esp8266](images/settings-esp8266.png) + +5. Open sketch to compile (File ➝ Examples ➝ AirGradient Air Quality Sensor ➝ ``). Depends on the DIY model, either `BASIC`, `DiyProIndoorV3_3` and `DiyProIndoorV4_2` +6. Compile + +![compiled esp8266](images/compiled-esp8266.png) + +## Possible Issues + +### Linux (Debian) + +ModuleNotFoundError: No module named ‘serial’ + +![Linux Failed](images/linux-failed.png) + +Make sure python pyserial module installed globally in the environment by executing: + +`$ sudo apt install -y python3-pyserial` + +or + +`$ pip install pyserial` + +Choose based on how python installed on your machine. But most user, using `apt` is better. + +## How to contribute + +Please follow github [contributing to a project](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project) tutorial to contribute to this project. + +There are 2 environment options to compile this project, PlatformIO and ArduinoIDE. + +- For PlatformIO, it should work out of the box +- For arduino, files in `src` folder and also from `Examples` can be modified at `Documents/Arduino/libraries` for windows and mac, and `~/Arduino/Libraries` for linux \ No newline at end of file diff --git a/docs/images/additional-board.png b/docs/images/additional-board.png new file mode 100644 index 0000000..a7c7803 Binary files /dev/null and b/docs/images/additional-board.png differ diff --git a/docs/images/ag-lib.png b/docs/images/ag-lib.png new file mode 100644 index 0000000..cf2d609 Binary files /dev/null and b/docs/images/ag-lib.png differ diff --git a/docs/images/compiled-esp8266.png b/docs/images/compiled-esp8266.png new file mode 100644 index 0000000..2ad6afd Binary files /dev/null and b/docs/images/compiled-esp8266.png differ diff --git a/docs/images/compiled.png b/docs/images/compiled.png new file mode 100644 index 0000000..9fed0b8 Binary files /dev/null and b/docs/images/compiled.png differ diff --git a/docs/images/esp32-board.png b/docs/images/esp32-board.png new file mode 100644 index 0000000..d6c9dbe Binary files /dev/null and b/docs/images/esp32-board.png differ diff --git a/docs/images/esp8266-board.png b/docs/images/esp8266-board.png new file mode 100644 index 0000000..bb6d780 Binary files /dev/null and b/docs/images/esp8266-board.png differ diff --git a/docs/images/linux-failed.png b/docs/images/linux-failed.png new file mode 100644 index 0000000..2b5e305 Binary files /dev/null and b/docs/images/linux-failed.png differ diff --git a/docs/images/settings-esp8266.png b/docs/images/settings-esp8266.png new file mode 100644 index 0000000..37989b6 Binary files /dev/null and b/docs/images/settings-esp8266.png differ diff --git a/docs/images/settings.png b/docs/images/settings.png new file mode 100644 index 0000000..a88e57e Binary files /dev/null and b/docs/images/settings.png differ diff --git a/examples/BASIC/BASIC.ino b/examples/BASIC/BASIC.ino index 09ad1ec..6fd718c 100644 --- a/examples/BASIC/BASIC.ino +++ b/examples/BASIC/BASIC.ino @@ -12,10 +12,8 @@ Outdoor Monitor: https://www.airgradient.com/outdoor/ Build Instructions: https://www.airgradient.com/documentation/diy-v4/ -Please make sure you have esp8266 board manager installed. Tested with -version 3.1.2. - -Set board to "LOLIN(WEMOS) D1 R2 & mini" +Compile Instructions: +https://github.com/airgradienthq/arduino/blob/master/docs/howto-compile.md Configuration parameters, e.g. Celsius / Fahrenheit or PM unit (US AQI vs ug/m3) can be set through the AirGradient dashboard. diff --git a/examples/DiyProIndoorV3_3/DiyProIndoorV3_3.ino b/examples/DiyProIndoorV3_3/DiyProIndoorV3_3.ino index 4966926..c80db45 100644 --- a/examples/DiyProIndoorV3_3/DiyProIndoorV3_3.ino +++ b/examples/DiyProIndoorV3_3/DiyProIndoorV3_3.ino @@ -12,10 +12,8 @@ Outdoor Monitor: https://www.airgradient.com/outdoor/ Build Instructions: https://www.airgradient.com/documentation/diy-v4/ -Please make sure you have esp8266 board manager installed. Tested with -version 3.1.2. - -Set board to "LOLIN(WEMOS) D1 R2 & mini" +Compile Instructions: +https://github.com/airgradienthq/arduino/blob/master/docs/howto-compile.md Configuration parameters, e.g. Celsius / Fahrenheit or PM unit (US AQI vs ug/m3) can be set through the AirGradient dashboard. diff --git a/examples/DiyProIndoorV4_2/DiyProIndoorV4_2.ino b/examples/DiyProIndoorV4_2/DiyProIndoorV4_2.ino index 0ae3dd2..92912bb 100644 --- a/examples/DiyProIndoorV4_2/DiyProIndoorV4_2.ino +++ b/examples/DiyProIndoorV4_2/DiyProIndoorV4_2.ino @@ -12,10 +12,8 @@ Outdoor Monitor: https://www.airgradient.com/outdoor/ Build Instructions: https://www.airgradient.com/documentation/diy-v4/ -Please make sure you have esp8266 board manager installed. Tested with -version 3.1.2. - -Set board to "LOLIN(WEMOS) D1 R2 & mini" +Compile Instructions: +https://github.com/airgradienthq/arduino/blob/master/docs/howto-compile.md Configuration parameters, e.g. Celsius / Fahrenheit or PM unit (US AQI vs ug/m3) can be set through the AirGradient dashboard. diff --git a/examples/OneOpenAir/OneOpenAir.ino b/examples/OneOpenAir/OneOpenAir.ino index 3202f12..7580bdf 100644 --- a/examples/OneOpenAir/OneOpenAir.ino +++ b/examples/OneOpenAir/OneOpenAir.ino @@ -14,17 +14,8 @@ https://www.airgradient.com/documentation/one-v9/ Build Instructions: AirGradient Open Air: https://www.airgradient.com/documentation/open-air-pst-kit-1-3/ -Please make sure you have esp32 board manager installed. Tested with -version 2.0.11. - -Important flashing settings: -- Set board to "ESP32C3 Dev Module" -- Enable "USB CDC On Boot" -- Flash frequency "80Mhz" -- Flash mode "QIO" -- Flash size "4MB" -- Partition scheme "Minimal SPIFFS (1.9MB APP with OTA/190KB SPIFFS)" -- JTAG adapter "Disabled" +Compile Instructions: +https://github.com/airgradienthq/arduino/blob/master/docs/howto-compile.md Configuration parameters, e.g. Celsius / Fahrenheit or PM unit (US AQI vs ug/m3) can be set through the AirGradient dashboard.