Commit cf89e850 authored by Nelso Jost's avatar Nelso Jost

ADD usage guide at README

parent c0cb43ab
# Meteorolog # Meteorolog
This repository contains several applications devoted to perform data logging of sensor data from the EMM boards: This repository contains several applications devoted to perform data logging of sensor data from the EMM boards (Modular Meteorological Station, or "Estações Meteorológicas Modulares" in portuguese).
* **Arduino firmware** -- Read sensor data upon serial commands like `read,dt,t` (which returns the RTC datetime and the temperature as comma-separated values); * Project main site: http://cta.if.ufrgs.br/projects/estacao-meteorologica-modular/wiki/Wiki
* Web app for open data storage: http://dados.cta.if.ufrgs.br/emm/
* **NodeMCU firmware** -- communicate with Arduino via software serial to retrieve sensor data and perform data logging into SD card and remote server via wifi (ESP8266); Applications included are:
* PyLogger software (Linux): alternative data logger that can run on a RaspberryPi with the Arduino plugged on the USB; * **Arduino firmware** - Read sensor data upon serial commands like `read,dt,t` (which returns the RTC datetime and the temperature as comma-separated values);
## Arduino Firmware * **NodeMCU firmware** - Communicate with Arduino via software serial to retrieve sensor data and perform data logging into SD card and remote server via wifi (ESP8266);
* **PyLogger software (Linux)** - Alternative data logger that can run on a RaspberryPi (or any Linux PC) with he Arduino plugged on the USB;
This document describe briefly how to get started using those applications. A more comprehensive documentation is present at the `/doc` directory of this repository.
## Arduino + NodeMCU Guide
What follow is a suscint list of steps to get your EMM board up and running using Arduino + NodeMCU.
### 1. Hardware assembling
The Modular Meteorological Station (EMM in portuguese) concept starts with the use of cheap but reliable sensors plugged onto the popular open-source hardware Arduino board. The basic kit includes: The Modular Meteorological Station (EMM in portuguese) concept starts with the use of cheap but reliable sensors plugged onto the popular open-source hardware Arduino board. The basic kit includes:
...@@ -17,25 +28,115 @@ The Modular Meteorological Station (EMM in portuguese) concept starts with the u ...@@ -17,25 +28,115 @@ The Modular Meteorological Station (EMM in portuguese) concept starts with the u
* LDR for reading luminosity (not calibrated for lux); * LDR for reading luminosity (not calibrated for lux);
* RTC DS1307/DS3231 (Real-time Clock) to provide reliable timestamps; * RTC DS1307/DS3231 (Real-time Clock) to provide reliable timestamps;
Reading of those sensores rely on great, easy-to-find, open-source libraries. You can install and use the firmware on a board with none or only some of the components. Some sensors are connected on dedicated GPIO pins like DHT22 and LDR and others onto an I2C bus, like BMP180 and RTC DS1307.
As for microcontrollers you'll need the following development boards:
* Arduino (Uno/Nano/Due): Have lots of GPIO and a very stable framework;
* NodeMCU (ESP8266-12): Cheapest wifi solution for IoT. Have less GPIO than Arduino;
Both boards already come with USB interface for easy upload of firmware.
Communication between Arduino and NodeMCU is done by Software Serial. Since the boards work on different voltages (Arduino with 5 V logic and NodeMCU with 3 V logic), you'll also need:
* Bidirectional level shifter (https://www.sparkfun.com/products/12009)
The assemblying steps are:
1. Connect all the sensors to the Arduino board.
2. Connect the Arduino TX/RX pins to the software serial RX/TX pins on NodeMCU (ex: D1/D2) using the level shifter;
3. (optional) connect the micro SD module to the NodeMCU board;
4. Use a good, regulated, 5V/1A power suply to power both boards (Vin/GND pins) at the same time;
* Suggestion: Battery charger (https://www.adafruit.com/product/2465)
### 2. Upload firmware
There are two firmwares you will need to install:
* `arduino/meteorolog` contains the code for the Arduino board;
* `nodemcu/esplogger` contains the code for the NodeMCU board;
Both are Arduino IDE compatible, which means that you can build/upload them simply using the standard IDE.
> Note: For the NodeMCU firmware you'll need to have IDE version >= 1.6 and follow the steps indicated here https://github.com/esp8266/Arduino#installing-with-boards-manager.
Alternatively you can use **PlatformIO** by executing `make <target>` commands inside the folders with a `Makefile`. Execute `make help` for a list of all actions, but the basic steps are:
> This firmware does not perform datalogging! It just read sensor data. 1. Make sure you have the tool with `make install-platformio` (need just once);
2. (Arduino only) Edit the Makefile `BOARD` variable with your board model;
* Run `platformio boards arduino` for listing all the models.
3. Simply execute `make` to build, upload and open serial monitor (port auto-detected).
### Installation For more info check `utils/platformio/Makefile`;
The Arduino-IDE-compatible firmware source code is inside the `arduino/meteorolog` directory. There are two options for compiling and upload to the board: ### 3. Test sensors
(i) Simply use the Arduino IDE. Open the `meteorolog.ino` file, select board model (ex: Uno), port (ex: `/dev/ttyACM0`) and click the right-arrow upload button; * Check all the available sensor names on the Arduino:
```
arduino listall
```
(ii) PlatformIO for those who like to stay on the terminal. * Check the reading of the sensors you want:
* The `arduino/Makefile` provide commands to make the proccess as easy as typing `make` to build, upload and open the serial monitor :-) ```
* Make sure you have the tool with `make install-platformio` (just once); arduino read,dt,t,p
* Edit the file's `BOARD` variable with your board model (check `platformio boards arduino` for all possible names); ```
* For more info check the full file at `utils/platformio/Makefile`; for instance will return the RTC datetime, temperature and pressure as comma-separated values.
### Usage ### 4. Setup wifi connection
* List available networks in range:
```
wifiscan
```
* Connect to one of them:
```
wificonnect <ssid> <password>
```
* Check your current status:
```
wifistatus
```
If you got an IP address, you good to go!
### 5. Setup server authentication
* Use your board credentials (from the site http://dados.cta.if.ufrgs.br/emm/).
```
setboard <board_id> <user_password>
```
This will communicate with the web site API for retrieving your `"board_hash"` authentication token.
Two things can go wrong:
1. If you got a `[HTTP] POST` message with code different from 200, you have a internet connection issue. Try a different network and/or reseting the board.
1. Code 200 means server communication is OK, but you can still get and `"error"` response for using wrong credentials. Double check CAPSLOCK and try it again.
If the configuration file `'LOGGER.CONF'` was sucessfully updated you should see a print of it containing the `"board_hash"` authentication token. This means that you are good to go: the configuration is stored on the NodeMCU flash memory and will be reloaded on board reset.
### 6. Start the data logger
* Assuming you already test your sensors (with `read,dt,t,p`), start the logger with a short interval like so:
```
meteorolog 0.5 read,dt,t,p
```
If all goes well, re-run this command with a larger interval.
This configuration will be stored on the internal configuration file and reload on board reset.
As for debuging you can follow the serial monitor messages for a while, or just watch how the built-in NodeMCU led blinks:
* 1 blink means everything is OK;
* 2 blinks means problem with the serial connection between Arduino and NodeMCU;
* 3 blinks means problem with the server connection (data was not uploaded, but saved on the SD card);
* 4 blinks means problem with the SD card only (data was sent to the server);
* 5 blinks means problem with both server and SD card (CRITICAL: data was lost!);
# Usage
## Arduino Firmware
Simply send a string with a valid board command via serial monitor or another serial tool and wait for the response. The `help` command list all of them: The following commands can be sent via serial monitor on the Arduino port:
* `read,<name1>,<name2>,...,<nameN>` * `read,<name1>,<name2>,...,<nameN>`
...@@ -57,6 +158,8 @@ Show the list of all available commands. ...@@ -57,6 +158,8 @@ Show the list of all available commands.
## NodeMCU firmware ## NodeMCU firmware
The following commands can be sent via serial monitor on the Arduino port:
* `help`: Lists all of the available commands.
## PyLogger firmware ## PyLogger
...@@ -47,12 +47,12 @@ void Meteorologger::update(void) ...@@ -47,12 +47,12 @@ void Meteorologger::update(void)
if (this->interval_minutes == 0) return; if (this->interval_minutes == 0) return;
String json=this->generate_json(); //String json=this->generate_json();
this->repl->log("\n[DEBUG] --- JSON created ---\n" + json); //this->repl->log("\n[DEBUG] --- JSON created ---\n" + json);
if (!this->server_upload(json)) //if (!this->server_upload(json))
{ //{
this->status_level = STATUS_ERROR_SERVER; //this->status_level = STATUS_ERROR_SERVER;
} //}
String datalog_line=this->arduino_response + "," + String( String datalog_line=this->arduino_response + "," + String(
(this->status_level == STATUS_ERROR_SERVER)? 0:1); (this->status_level == STATUS_ERROR_SERVER)? 0:1);
...@@ -216,7 +216,7 @@ void Meteorologger::set_board(int board_id, String user_password) ...@@ -216,7 +216,7 @@ void Meteorologger::set_board(int board_id, String user_password)
} }
else else
{ {
this->repl->log("[DEBUG] Response:\n" + response); this->repl->log("\n[DEBUG] Response:\n" + response);
} }
} }
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment