The Gateway provides a WiFi hotspot for configuration. The hotspot has SSID with the name "Configure Ruuvi Gateway ABCD" where ABCD is the last 2 bytes of the gateway WiFi MAC address. No password is required to connect to the gateway's hotspot.
The WiFi hotspot is only active if the gateway is not configured or within one minute after pressing the Configuration button. After the configuration of the gateway is complete, WiFi credentials are stored to flash and the hotspot is turned off. If the Internet connection is lost later, connection loss is indicated by "Red LED" but the hotspot is not turned back on unless the user enters configuration mode by pressing the Configuration button.
The gateway can be partially reconfigured over LAN (network configuration can't be changed in this case). Also following pages are available through LAN connection: /metrics and /history.
If Ethernet cable is connected to an unconfigured gateway, then after one minute the gateway will automatically be set to the default configuration with Ethernet connection mode and the Wi-Fi hotspot will be deactivated. After that, the user can activate the hotspot with a short press on the "Configure" button or reset the configuration with a long press on the "Configure" button.
API
The gateway is reachable at http://10.10.0.1 once a client has connected to the hotspot.
Encrypted data format
Sensitive data (containing passwords) is transmitted in encrypted form. The format for transmitting encrypted data is as follows (JSON):
The data is encrypted using AES-256-CBC. ECDH protocol is used to establish a shared secret between the client and the Gateway, then SHA-256 hash is calculated for the shared secret to generate AES encryption key.
To establish a shared secret, the client must perform GET /ruuvi.json request and pass its public encryption key in the HTTP header "ruuvi_ecdh_pub_key" (Base64 encoded):
The client needs to compute a shared secret using its private encryption key and the Gateway's public key, then calculate SHA-256 for the shared secret to get the AES encryption key (AES_K).
To encrypt the data before sending it, the client must randomly generate a 16-byte initialization vector (IV) for AES encryption, then encrypt the data using parameters IV and AES_K. The data is validated using a SHA-256 hash, which is passed as part of JSON. All values in JSON are encoded by Base64.
To decrypt the data received from the Gateway, the client needs to decode all values in JSON from Base64 encoding, then get the IV from the "iv" attribute of the received JSON. After that, decrypt the data in the "encrypted" attribute using the IV and AES_K. And finally, calculate the SHA-256 hash for the decrypted data and check if it matches the "hash" attribute in JSON.
These API calls are available:
Requesting gateway configuration and performing encryption keys exchange
The same endpoint "/ruuvi.json" is used for saving the network configuration and gateway configuration. If the passed JSON data contains the "use_eth" attribute, then the network part of the configuration will be updated. Otherwise, the gateway configuration will be set.
The data must be sent in an encrypted form (see Encrypted data format). Here is the unencrypted data:
Request Body
{// Response}
Example:
{"use_eth":true,"eth_dhcp":true}
Example:
{"use_eth":false,"wifi_ap_config":{"channel":11}}
Save gateway configuration
POSThttp://10.10.0.1/ruuvi.json
The same endpoint "/ruuvi.json" is used for saving the network configuration and gateway configuration. If the passed JSON data contains the "use_eth" attribute, then the network part of the configuration will be updated. Otherwise, the gateway configuration will be set.
The data must be sent in an encrypted form (see Encrypted data format). Here is the unencrypted data:
Example of unencrypted data for connecting to Wi-Fi with the name "my_ssid1" using the saved password (the value "null" is passed to indicate that the saved value of the password is to be used):
{"ssid":"my_ssid1","password":null,"stub":" "}
Example of unencrypted data for connecting to Ethernet:
{"ssid":null,"password":null,"stub":" "}
connect.json
DELETEhttp://10.10.0.1/connect.json
Disconnect from WiFi or Ethernet.
{}
metrics
GEThttp://10.10.0.1/metrics
Get machine statistics, such as uptime and free memory. Data is in Prometheus format. For more details, please see https://prometheus.io/docs/instrumenting/exposition_formats/ .
