README.md

# ICBM Arduino Firmware

ESP32 firmware for the ICBM, based on Arduino and the `ESP32-Ethernet-Kit_A_V1.2`.
The Intelligent Controller Board for MPODs is a project that aims to automatically
perform power procedures upon defined inputs.  


This project depends on [`Arduino_SNMP`](https://github.com/patricklaf/SNMP) and [`MCP23S08`](https://github.com/RobTillaart/MCP23S08).

## Usage
The IMC is meant to be used over network using HTTP get and post.

### Routes
All routes return JSON.

Available routes are:

- `/idn`: provides information about firmware and hardware version, and uptime.  
It can be queried as a heartbeat, seeing the uptime increasing.

### Serial Interface

The serial interface is available through the micro-usb port.
It prints basic networking information, as well as a heartbeat (`-` if ethernet is disconnected, else `.`).  
It is not possible to control the device or perform queries through the serial interface.


## Development

### Quirks

Despite communication being over Ethernet, the project makes use of the ESP32 Wifi stack, hence some
references to Wifi here and there (eg. `WiFiUdp`).


### Installation
Either use the Arduino IDE and use its library manager to find the SNMP library, or use `arduino-cli`:  

```bash
# Download arduino-cli
wget https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Linux_64bit.tar.gz

# Extract the downloaded archive
tar -xzf arduino-cli_latest_Linux_64bit.tar.gz


# Verify installation
arduino-cli config init
```

Then set up the required environment. Edit `~/.arduino15/arduino-cli.yaml` and add the following:

```yaml
board_manager:
    additional_urls:
      - https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
      - http://arduino.esp8266.com/stable/package_esp8266com_index.json
library:
    enable_unsafe_install: true
```

We enable unsafe installation to allow installation of packages outside of the Arduino package registry (ie. via git)


Update the Arduino index with:

	arduino-cli core update-index

The required libraries are (minimum versions):

    arduino-cli lib install ethernet
    arduino-cli lib install --git-url https://github.com/patricklaf/SNMP.git --config-file arduino-cli.yaml  # Awaiting 1.4.1+ tag
    arduino-cli lib install MCP23S08@0.5.2


`SNMP` needs to be installed from Git until a new release (greater than 1.4.0) is released due to compilation issues with arduino-esp 3+.  
This is fixed in master, but not tagged and released in the Arduino library list.

The project can be compiled so:

    arduino-cli compile -b esp32:esp32:esp32wroverkit icbm.ino -v

And uploaded so:

    arduino-cli upload -p /dev/ttyUSB1 -b esp32:esp32:esp32wroverkit


### Versioning

The firmware version is provided as part of the `/idn` route.  
This is the git tag or commit, if `-DICBM_GIT_VERSION` is set.  
The git date can be set via `-DICBM_GIT_TIMESTAMP`.  

### CI Artefacts

CI artefacts can be uploaded so:

    unzip icbm-0.0.0.zip
    arduino-cli upload -p /dev/ttyUSB1 -b esp32:esp32:esp32wroverkit --input-dir icbm-0.0.0