README.md

# CO<sub>2</sub> Ampel

*CO<sub>2</sub> Ampel* is an open-source project, written in C++ for [ESP8266](https://en.wikipedia.org/wiki/ESP8266) or [ESP32](https://en.wikipedia.org/wiki/ESP32).

It measures the current CO<sub>2</sub> concentration (in ppm), and displays it on an LED ring.

The room should be ventilated as soon as one LED turns red.

## Features

The *CO<sub>2</sub> Ampel* can:

* Display CO<sub>2</sub> concentration on LED ring.
* Allow calibration.
* Get current time over [NTP](https://en.wikipedia.org/wiki/Network_Time_Protocol)
* Send data over [MQTT](https://en.wikipedia.org/wiki/MQTT).
* Send data over [LoRaWAN](https://en.wikipedia.org/wiki/LoRa#LoRaWAN).
* Display measurements and configuration on a small website.
* Allow configuration of every parameter via web-interface.
* Log data to a [CSV](https://en.wikipedia.org/wiki/Comma-separated_values) file, directly on the ESP flash memory.
* Accept many interactive commands.

## Hardware Requirements

* [ESP8266](https://en.wikipedia.org/wiki/ESP8266) or [ESP32](https://en.wikipedia.org/wiki/ESP32) microcontroller (this project has been tested with *ESP8266 ESP-12 WIFI* and *TTGO ESP32 SX1276 LoRa*)
* [Sensirion SCD30](https://www.sensirion.com/en/environmental-sensors/carbon-dioxide-sensors/carbon-dioxide-sensors-co2/) "Sensor Module for HVAC and Indoor Air Quality Applications"
* [NeoPixel Ring - 12](https://www.adafruit.com/product/1643), or [NeoPixel Ring - 16](https://www.adafruit.com/product/1463) (experimental)

See the [documentation](https://transfer.hft-stuttgart.de/gitlab/co2ampel/ampel-documentation) for more info.

## Software Requirements

* [PlatformIO](https://platformio.org/)
or
* [Arduino IDE](https://www.arduino.cc/en/software)

## Installation

* If `config.h` does not exist, copy it from `config.public.h`
* You can modify `config.h`, e.g. for measurement time-steps, WiFi access, MQTT, NTP and web-server.
* Every parameter can be modified later, via the web-interface.

### PlatformIO

PlatformIO can be run from [VSCODE](https://platformio.org/install/ide?install=vscode), [Eclipse CDT](https://www.eclipse.org/cdt/) or console:

```bash
make upload board=esp8266 && make monitor # For ESP8266
```
```bash
make upload board=esp32 && make monitor # For ESP32
```

### Arduino IDE

* All the libraries are included in this repository. No need to install anything via *Library Manager*.

* Add your board to the [board manager](https://github.com/esp8266/Arduino#installing-with-boards-manager). Either ESP8266:

        http://arduino.esp8266.com/stable/package_esp8266com_index.json

  or ESP32:

        https://dl.espressif.com/dl/package_esp32_index.json

* Choose the correct board in *Tools > Board > ...*
* Choose the correct *Flash size* (e.g. "Flash Size : 4MB (1MB FS, OTA:~1019kB)" for *ESP8266 ESP-12 WIFI*)

* *Verify*
* *Upload*
* *Tools > Serial Monitor*

## Usage and configuration

* Start the *Ampel*
* If you didn't define wifi SSID and Passwords in config.h
    * The *Ampel* should blink turquoise, to indicate *Access Point* mode.
    * Connect with a laptop/smartphone to ESPxxxxxx WiFi.
    * Open a browser, it should bring you to the *Ampel* web-page.
    * The *Ampel* web-page will be shown. You can click on "Configuration".
    * You'll have to set an *Ampel* password with at least 8 characters.
    * You can set WiFi SSID + Password if you want. It will then try to connect if you disconnect from the *Access Point*.
    * If you don't specify SSID + Password, the *Ampel* will simply stay in *Access Point* mode.
    * The *Ampel* password will be required if a connection fails, and the *Access Point* starts again.
    * The *Ampel* password will be needed (with user 'admin') to connect to the config web-page once the *Ampel* is connected to WiFi.
* Once you defined Wifi SSID, Ampel password and WiFi password:
    * the *Ampel* will try to connect, displaying a rainbow wheel.
    * if the connection is successful, LEDs will be green.
    * if the connection fails, LEDs will be red, and the *Ampel* will return back to *Access Point* mode.
* It might be necessary to reset the *Ampel* after changing important parameters.
* You can rename the *Ampel*. This name will be used instead of ESPxxxxxx for CSV files and the mDNS address. You'll get a new CSV file after renaming, which can be convenient, e.g. to indicate at which location the measurements were made.
* If you forgot the password, you can send `reset_config` as command, and `reset` the ampel.
* If you disabled WiFi, you can enable it again with `wifi 1`.
* It's also possible to specify WiFi SSID and password in the console, with `ssid wifi_ssid_here` and `pwd wifi_password_here` commands.
* You can enable CSV by clicking on "+CSV", or disable it by clicking on "Disable CSV".
* The same applies to MQTT and LoRaWAN.
* If you disable a set, the parameters are still saved, and will appear again once the service is enabled.



## Available commands

In Arduino IDE *Serial Monitor* or PlatformIO *Monitor*, type `help` + <kbd>Enter</kbd> in order to list the available commands:

* `ap 0/1` (Disables/enables access point).
* `auto_calibrate 0/1` (Disables/enables autocalibration).
* `calibrate 600` (Starts calibration process, to given ppm).
* `calibrate` (Starts calibration process).
* `calibrate! 600` (Calibrates right now, to given ppm).
* `co2 1500` (Sets CO<sub>2</sub> level, for debugging).
* `color 0xFF0015` (Shows color, specified as RGB, for debugging).
* `csv 60` (Sets CSV writing interval, in s).
* `format_filesystem` (Deletes the whole filesystem).
* `free` (Displays available heap space).
* `led 0/1` (Turns LEDs on/off).
* `local_ip` (Displays local IP and current SSID).
* `lora 300` (Sets LoRaWAN sending interval, in s).
* `mqtt 60` (Sets MQTT sending interval, in s).
* `pwd abc` (Sets WiFi password to 'abc').
* `reset` (Restarts the ESP).
* `reset_config` (Resets the complete IotWeb config).
* `reset_scd` (Resets SCD30).
* `save_config` (Saves the config to EEPROM).
* `send_local_ip` (Sends local IP and SSID via MQTT. Can be useful to find sensor).
* `set_time 1618829570` (Sets time to the given UNIX time).
* `show_csv` (Displays the complete CSV file on Serial).
* `ssid name` (Sets SSID to 'name').
* `timer 30` (Sets measurement interval, in s).
* `wifi 0/1` (Turns Wifi on/off).
* `wifi_scan` (Scans available WiFi networks).

The commands can be sent via the Serial interface, from the webpage or via MQTT.

## Authors

 * Eric Duminil (HfT Stuttgart)
 * Robert Otto (HfT Stuttgart)
 * Myriam Guedey (HfT Stuttgart)
 * Tobias Gabriel Erhart (HfT Stuttgart)
 * Jonas Stave (HfT Stuttgart)
 * Michael Käppler

## Contributing

* Merge requests are welcome, and should be based on the `develop` branch.
* The `develop` branch gets merged into the `master` once it has been sufficiently tested.
* For major changes, please open an issue first to discuss what you would like to change.

## License

Copyright © 2022, [HfT Stuttgart](https://www.hft-stuttgart.de/)
[GPLv3](https://choosealicense.com/licenses/gpl-3.0/)