Gateway configuration
This format is used both for storing the gateway configuration and for reading/writing it.
Depending on how the configuration is used, some data may be excluded. For example, when reading the configuration via HTTP, it does not contain passwords. When writing the configuration, all missing fields retain their previous values.
This data format is used in the following cases:
Storing the Gateway configuration in the internal flash memory
Configuring the default gateway configuration (gw_cfg_default.json) on the separate "gw_cfg_def" partition. Some attributes can be omitted, in this case, the hard-coded defaults will be used.
Reading configuration from the Gateway via HTTP using API GET "/ruuvi.json". All passwords are excluded in this case. Additional informational attributes will be added to the generated json:
fw_ver,nrf52_fw_ver,gw_mac.Writing network part of the configuration to the Gateway via HTTP using API POST "/ruuvi.json". Only the
use_ethattribute andeth_...orwifi_...attributes are used in this case, other attributes will be ignored.Writing the main part of the configuration to the Gateway via HTTP using API POST "/ruuvi.json" The
use_ethattribute should not be present in json, all network-related attributes will be ignored.Automatic configuration downloading from a remote server
Example of the default configuration
{
"wifi_sta_config": {
"ssid": "",
"password": ""
},
"wifi_ap_config": {
"password": "",
"channel": 1
},
"use_eth": true,
"eth_dhcp": true,
"eth_static_ip": "",
"eth_netmask": "",
"eth_gw": "",
"eth_dns1": "",
"eth_dns2": "",
"remote_cfg_use": false,
"remote_cfg_url": "",
"remote_cfg_auth_type": "no",
"remote_cfg_auth_bearer_token": "",
"remote_cfg_auth_basic_user": "",
"remote_cfg_auth_basic_pass": "",
"remote_cfg_refresh_interval_minutes": 0,
"use_http_ruuvi": true,
"use_http": true,
"http_url": "https://network.ruuvi.com/record",
"http_data_format": "ruuvi",
"http_auth": "none",
"use_http_stat": true,
"http_stat_url": "https://network.ruuvi.com/status",
"http_stat_user": "",
"http_stat_pass": "",
"use_mqtt": false,
"mqtt_disable_retained_messages": false,
"mqtt_transport": "TCP",
"mqtt_server": "test.mosquitto.org",
"mqtt_port": 1883,
"mqtt_prefix": "",
"mqtt_client_id": "",
"mqtt_user": "",
"mqtt_pass": "",
"lan_auth_type": "lan_auth_default",
"lan_auth_api_key": "",
"lan_auth_api_key_rw": "",
"auto_update_cycle": "regular",
"auto_update_weekdays_bitmask": 127,
"auto_update_interval_from": 0,
"auto_update_interval_to": 24,
"auto_update_tz_offset_hours": 3,
"ntp_use": true,
"ntp_use_dhcp": false,
"ntp_server1": "time.google.com",
"ntp_server2": "time.cloudflare.com",
"ntp_server3": "time.nist.gov",
"ntp_server4": "pool.ntp.org",
"company_use_filtering": true,
"company_id": 1177,
"scan_coded_phy": false,
"scan_1mbit_phy": true,
"scan_extended_payload": true,
"scan_channel_37": true,
"scan_channel_38": true,
"scan_channel_39": true,
"scan_filter_allow_listed": false,
"scan_filter_list": [],
"coordinates": ""
}
Examples of network configuration
Here is the example of json to configure Gateway to use Ethernet:
{
"use_eth": true,
"eth_dhcp": true
}Here is the example of json to configure Gateway to use WiFi and activate WiFi access point on channel 7:
{
"use_eth": false,
"wifi_ap_config": {
"channel": 7
}
}JSON schema
The format of this JSON file is described as JSON schema, which provides human- and machine- readable documentation. The JSON schema also contains examples both for each of the properties and for the whole file. The example at the end of JSON schema contains default settings for Ruuvi Gateway.
{
"$schema": "https://json-schema.org/draft/2019-09/schema",
"$id": "http://ruuvi.com/schemas/ruuvi_gw_cfg.schema.json",
"title": "Ruuvi gateway configuration",
"type": "object",
"additionalProperties": false,
"required": [
],
"properties": {
"fw_ver": {
"title": "Current firmware version",
"description": "This field is generated only when configuration is requested via HTTP.",
"type": "string",
"examples": [
"v1.13.1"
]
},
"nrf52_fw_ver": {
"title": "Current firmware version of nRF52",
"description": "This field is generated only when configuration is requested via HTTP.",
"type": "string",
"examples": [
"v1.0.0"
]
},
"gw_mac": {
"title": "Gateway MAC address",
"description": "This field is generated only when configuration is requested via HTTP.",
"type": "string",
"examples": [
"C8:25:2D:8E:9C:2C"
]
},
"storage": {
"title": "SSL certificates storage info",
"description": "This field is generated only when configuration is requested via HTTP.",
"type": "object",
"required": [
"storage_ready",
"http_cli_cert",
"http_cli_key",
"http_srv_cert",
"stat_cli_cert",
"stat_cli_key",
"stat_srv_cert",
"mqtt_cli_cert",
"mqtt_cli_key",
"mqtt_srv_cert",
"rcfg_cli_cert",
"rcfg_cli_key",
"rcfg_srv_cert"
],
"properties": {
"storage_ready": {
"type": "boolean",
"title": "Status of storage"
},
"http_cli_cert": {
"type": "boolean",
"title": "Status of SSL client certificate for HTTP target"
},
"http_cli_key": {
"type": "boolean",
"title": "Status of SSL client private key for HTTP target"
},
"http_srv_cert": {
"type": "boolean",
"title": "Status of SSL server certificate for HTTP target"
},
"stat_cli_cert": {
"type": "boolean",
"title": "Status of SSL client certificate for Statistics"
},
"stat_cli_key": {
"type": "boolean",
"title": "Status of SSL client private key for Statistics"
},
"stat_srv_cert": {
"type": "boolean",
"title": "Status of SSL server certificate for Statistics"
},
"mqtt_cli_cert": {
"type": "boolean",
"title": "Status of SSL client certificate for MQTT"
},
"mqtt_cli_key": {
"type": "boolean",
"title": "Status of SSL client private key for MQTT"
},
"mqtt_srv_cert": {
"type": "boolean",
"title": "Status of SSL server certificate for MQTT"
},
"rcfg_cli_cert": {
"type": "boolean",
"title": "Status of SSL client certificate for the remote configuration server"
},
"rcfg_cli_key": {
"type": "boolean",
"title": "Status of SSL client private key for the remote configuration server"
},
"rcfg_srv_cert": {
"type": "boolean",
"title": "Status of SSL server certificate for the remote configuration server"
}
}
},
"wifi_sta_config": {
"title": "Wi-Fi credentials",
"description": "Gateway will connect to the specified WiFi SSID if it's not empty. Note: 'use_eth' should be 'false'",
"type": "object",
"required": [
"ssid"
],
"properties": {
"ssid": {
"type": "string",
"title": "WiFi network name (SSID)",
"examples": [
"",
"MyWiFi_123"
]
},
"password": {
"type": "string",
"title": "WiFi password",
"examples": [
"",
"my_password"
]
}
},
"examples": [
{
"ssid": "",
"password": ""
},
{
"ssid": "MyWiFi_123",
"password": "my_password"
}
]
},
"wifi_ap_config": {
"title": "WiFi access point default settings",
"type": "object",
"required": [
],
"properties": {
"password": {
"type": "string",
"default": "",
"title": "Default password for connecting to RuuviGatewayXXXX access point",
"examples": [
"",
"12345678"
]
},
"channel": {
"type": "integer",
"default": 1,
"title": "Default channel for Wi-Fi access point"
}
}
},
"use_eth": {
"title": "Network connection type: Ethernet/WiFi",
"type": "boolean"
},
"eth_dhcp": {
"title": "IP configuration mode (DHCP/manual) when connected via Ethernet",
"type": "boolean",
"default": true
},
"eth_static_ip": {
"title": "Manual IP configuration: IP address",
"type": "string"
},
"eth_netmask": {
"title": "Manual IP configuration: Subnet mask",
"type": "string"
},
"eth_gw": {
"title": "Manual IP configuration: Network gateway IP address",
"type": "string"
},
"eth_dns1": {
"title": "Manual IP configuration: IP address of DNS server1",
"type": "string"
},
"eth_dns2": {
"title": "Manual IP configuration: IP address of DNS server2",
"type": "string"
},
"remote_cfg_use": {
"title": "Enable automatic downloading of Gateway configuration from a remote server",
"type": "boolean",
"default": false
},
"remote_cfg_url": {
"title": "URL of the remote server for automatic Gateway configuration downloading",
"type": "string"
},
"remote_cfg_auth_type": {
"title": "HTTP authentication credentials for the remote configuration server for automatic Gateway configuration downloading",
"description": "It should not be empty if 'remote_cfg_use' is 'true'",
"type": "string",
"pattern": "^(|none|no|basic|bearer)$",
"default": "",
"examples": [
"",
"none",
"basic",
"bearer"
]
},
"remote_cfg_auth_bearer_token": {
"title": "A token for HTTP bearer authentication for the remote configuration server for automatic Gateway configuration downloading",
"type": "string"
},
"remote_cfg_auth_basic_user": {
"title": "Username for HTTP basic authentication for the remote configuration server for automatic Gateway configuration downloading",
"type": "string"
},
"remote_cfg_auth_basic_pass": {
"title": "Password for HTTP basic authentication for the remote configuration server for automatic Gateway configuration downloading",
"type": "string"
},
"remote_cfg_refresh_interval_minutes": {
"title": "Period for checking a new gateway configuration on the remote configuration server (in minutes)",
"type": "integer"
},
"remote_cfg_use_ssl_client_cert": {
"title": "Enable use of SSL client certificate for authentication on the remote configuration server",
"type": "boolean",
"default": false
},
"remote_cfg_use_ssl_server_cert": {
"title": "Enable use of SSL server certificate to authenticate the remote configuration server",
"type": "boolean",
"default": false
},
"use_http_ruuvi": {
"title": "Enable HTTP relaying mode to Ruuvi cloud",
"type": "boolean",
"default": true
},
"use_http": {
"title": "Enable HTTP relaying mode to a custom server",
"type": "boolean",
"default": false
},
"http_data_format": {
"title": "Data format used for HTTP transmission",
"type": "string",
"pattern": "^(|ruuvi)$",
"default": "ruuvi",
"examples": [
"ruuvi"
]
},
"http_auth": {
"title": "HTTP authentication type",
"type": "string",
"pattern": "^(|none|basic|bearer|token)$",
"default": "none",
"examples": [
"",
"none",
"basic",
"bearer",
"token"
]
},
"http_url": {
"title": "URL of the server to which the data collected from Bluetooth sensors will be sent",
"type": "string",
"default": "https://network.ruuvi.com/record",
"examples": [
"https://network.ruuvi.com/record",
"http://my_server123.com:8080/record"
]
},
"http_period": {
"title": "Period of sending data via HTTP(S)",
"type": "integer",
"default": 10,
"examples": [
10,
60
]
},
"http_user": {
"title": "Username for HTTP basic authentication for the server",
"type": "string",
"default": ""
},
"http_pass": {
"title": "Password for HTTP basic authentication for the server",
"type": "string",
"default": ""
},
"http_bearer_token": {
"title": "Bearer token used for authentication",
"description": "Bearer token is used when http_auth equals to 'bearer'",
"type": "string",
"default": ""
},
"http_api_key": {
"title": "API key used for authentication",
"description": "This API key is used when http_auth equals to 'token'",
"type": "string",
"default": ""
},
"http_use_ssl_client_cert": {
"title": "Enable use of SSL client certificate for authentication on the HTTPS server",
"type": "boolean",
"default": false
},
"http_use_ssl_server_cert": {
"title": "Enable use of SSL server certificate to authenticate the HTTPS server",
"type": "boolean",
"default": false
},
"use_http_stat": {
"title": "Enable sending Gateway status to the HTTP-server",
"type": "boolean",
"default": true
},
"http_stat_url": {
"title": "URL of the server to which the gateway status will be sent",
"type": "string",
"default": "https://network.ruuvi.com/status",
"examples": [
"https://network.ruuvi.com/status",
"http://my_server123.com:8080/status"
]
},
"http_stat_user": {
"title": "Username for HTTP basic authentication for the server",
"type": "string",
"default": ""
},
"http_stat_pass": {
"title": "Password for HTTP basic authentication for the server",
"type": "string",
"default": ""
},
"http_stat_use_ssl_client_cert": {
"title": "Enable use of SSL client certificate for authentication on the statistics server",
"type": "boolean",
"default": false
},
"http_stat_use_ssl_server_cert": {
"title": "Enable use of SSL server certificate to authenticate the statistics server",
"type": "boolean",
"default": false
},
"use_mqtt": {
"title": "Enable MQTT relaying mode",
"type": "boolean",
"default": false
},
"mqtt_disable_retained_messages": {
"title": "Disable MQTT retained messages",
"type": "boolean",
"default": false
},
"mqtt_transport": {
"title": "MQTT transport type to use",
"description": "TCP - MQTT over TCP, SSL - MQTT over SSL, WS - MQTT over WebSockets, WSS - MQTT over secure WebSockets",
"type": "string",
"pattern": "^(TCP|SSL|WS|WSS)$",
"default": "TCP",
"examples": [
"TCP",
"SSL",
"WS",
"WSS"
]
},
"mqtt_data_format": {
"title": "Data format used for MQTT transmission",
"description": "ruuvi_raw - raw data only, ruuvi_raw_and_decoded - raw and decoded data, ruuvi_decoded - decoded data only",
"type": "string",
"pattern": "^(ruuvi_raw|ruuvi_raw_and_decoded|ruuvi_decoded)$",
"default": "ruuvi_raw",
"examples": [
"ruuvi_raw",
"ruuvi_raw_and_decoded",
"ruuvi_decoded"
]
},
"mqtt_server": {
"title": "MQTT server address",
"type": "string",
"examples": [
"test.mosquitto.org"
]
},
"mqtt_port": {
"title": "MQTT server port",
"type": "integer",
"default": 1883,
"examples": [
1883,
8886,
8080,
8081
]
},
"mqtt_prefix": {
"title": "MQTT topic prefix",
"description": "Full MQTT topic is formed by joining the prefix and Bluetooth-sensor's MAC-address. If 'mqtt_prefix' is empty, then default prefix is used: 'ruuvi/<gateway_MAC_address>/'",
"type": "string",
"default": "",
"examples": [
"ruuvi/C8:25:2D:8E:9C:2C/"
]
},
"mqtt_client_id": {
"title": "MQTT client ID",
"description": "If 'mqtt_client_id' is empty, then default client ID is used: '<gateway_MAC_address>'",
"type": "string",
"default": "",
"examples": [
"",
"C8:25:2D:8E:9C:2C",
"my_mqtt_client1"
]
},
"mqtt_user": {
"title": "User name for MQTT authentication",
"type": "string",
"default": ""
},
"mqtt_pass": {
"title": "Password for MQTT authentication",
"type": "string",
"default": ""
},
"mqtt_use_ssl_client_cert": {
"title": "Enable use of SSL client certificate for authentication on the MQTT server",
"type": "boolean",
"default": false
},
"mqtt_use_ssl_server_cert": {
"title": "Enable use of SSL server certificate to authenticate the MQTT server",
"type": "boolean",
"default": false
},
"lan_auth_type": {
"title": "Configuring the authentication type when accessing Gateway from LAN",
"description": "'lan_auth_default' - Ruuvi-authentication with username 'Admin' and as a password the Unique ID is used (in format XX:XX:XX:XX:XX:XX:XX:XX) which is printed on the bottom of the Ruuvi Gateway. 'lan_auth_ruuvi' - Ruuvi-authentication, login/password should be specified in 'lan_auth_user' and 'lan_auth_pass'. 'lan_auth_deny' - deny access from LAN. 'lan_auth_allow' - allow access from LAN without a password. 'lan_auth_basic' - HTTP basic authentication, login/password should be specified in 'lan_auth_user' and 'lan_auth_pass'. 'lan_auth_digest' - HTTP digest authentication, login/password should be specified in 'lan_auth_user' and 'lan_auth_pass'.",
"type": "string",
"pattern": "^(lan_auth_default|lan_auth_ruuvi|lan_auth_deny|lan_auth_allow|lan_auth_basic|lan_auth_digest)$",
"default": "lan_auth_default",
"examples": [
"lan_auth_default",
"lan_auth_ruuvi",
"lan_auth_deny",
"lan_auth_allow",
"lan_auth_basic",
"lan_auth_digest"
]
},
"lan_auth_user": {
"title": "Login for authentication when accessing from LAN",
"type": "string",
"default": "Admin",
"examples": [
"Admin"
]
},
"lan_auth_pass": {
"title": "Password for authentication when accessing from LAN",
"type": "string"
},
"lan_auth_api_key_use": {
"title": "Use API key (token) for HTTP bearer authentication for read-only access from LAN",
"description": "This field is generated when configuration is read via HTTP ('lan_auth_api_key' is not generated in this case)",
"type": "boolean"
},
"lan_auth_api_key": {
"title": "API key (token) for HTTP bearer authentication for read-only access from LAN",
"description": "If 'lan_auth_api_key' is empty, then bearer authentication is disabled.",
"type": "string",
"default": "",
"examples": [
"304uOrJMoCNEVaPaXswV9U1qRDPZFbl0V2x7OXHM5nw="
]
},
"lan_auth_api_key_rw_use": {
"title": "Use API key (token) for HTTP bearer authentication for read/write access from LAN",
"description": "This field is generated when configuration is read via HTTP ('lan_auth_api_key_rw' is not generated in this case)",
"type": "boolean"
},
"lan_auth_api_key_rw": {
"title": "API key (token) for HTTP bearer authentication for read/write access from LAN",
"description": "If 'lan_auth_api_key_rw' is empty, then bearer authentication is disabled.",
"type": "string",
"default": "",
"examples": [
"304uOrJMoCNEVaPaXswV9U1qRDPZFbl0V2x7OXHM5nw="
]
},
"auto_update_cycle": {
"title": "Configure firmware auto-updating rules.",
"description": "'regular' - check for updates 1-2 times a day according to the schedule, install new versions only 2 weeks after release. 'beta' - install new versions as soon as a new version is released. 'manual' - do not check for firmware updates and do not install updates automatically",
"type": "string",
"pattern": "^(regular|beta|manual)$",
"default": "regular",
"examples": [
"regular",
"beta",
"manual"
]
},
"auto_update_weekdays_bitmask": {
"title": "Configure firmware auto-updating schedule: specify weekdays",
"description": "Bit-mask for weekdays: bit 0 - Sunday, bit 1 - Monday, ..., bit 6 - Saturday",
"type": "integer",
"default": 127,
"examples": [
1,
3,
127
]
},
"auto_update_interval_from": {
"title": "Configure firmware auto-updating schedule: start time (local timezone)",
"description": "0 - 00:00, 1 - 01:00, 2 - 02:00, ..., 23 - 23:00",
"type": "integer",
"default": 0,
"examples": [
0,
1,
23
]
},
"auto_update_interval_to": {
"title": "Configure firmware auto-updating schedule: end time (local timezone)",
"description": "1 - 01:00, 2 - 02:00, ..., 24 - 24:00",
"type": "integer",
"default": 24,
"examples": [
1,
23,
24
]
},
"auto_update_tz_offset_hours": {
"title": "Configure firmware auto-updating schedule: local timezone offset (hours)",
"type": "integer",
"default": 3,
"examples": [
3
]
},
"ntp_use": {
"title": "Enable time synchronization from NTP servers",
"type": "boolean",
"default": true
},
"ntp_use_dhcp": {
"title": "Use DHCP to get the list of NTP servers",
"type": "boolean",
"default": false
},
"ntp_server1": {
"title": "Address of NTP server 1 (used only if 'ntp_use_dhcp' is false).",
"type": "string",
"default": "time.google.com",
"examples": [
"time.google.com"
]
},
"ntp_server2": {
"title": "Address of NTP server 2 (used only if 'ntp_use_dhcp' is false).",
"type": "string",
"default": "time.cloudflare.com",
"examples": [
"time.cloudflare.com"
]
},
"ntp_server3": {
"title": "Address of NTP server 3 (used only if 'ntp_use_dhcp' is false).",
"type": "string",
"default": "pool.ntp.org",
"examples": [
"pool.ntp.org"
]
},
"ntp_server4": {
"title": "Address of NTP server 4 (used only if 'ntp_use_dhcp' is false).",
"type": "string",
"default": "time.ruuvi.com",
"examples": [
"time.ruuvi.com"
]
},
"company_use_filtering": {
"title": "Enable filtering messages from Bluetooth sensors by company ID.",
"type": "boolean",
"default": true
},
"company_id": {
"title": "Company ID for filtering messages from Bluetooth-sensors.",
"type": "integer",
"default": 1177,
"examples": [
1177
]
},
"scan_coded_phy": {
"title": "Configure Bluetooth scanning: Use coded PHY (long range)",
"type": "boolean",
"default": false
},
"scan_1mbit_phy": {
"title": "Configure Bluetooth scanning: Use Use 1 MBit/s PHY",
"type": "boolean",
"default": true
},
"scan_extended_payload": {
"title": "Configure Bluetooth scanning: Use extended payload",
"type": "boolean",
"default": true
},
"scan_channel_37": {
"title": "Configure Bluetooth scanning: Use channel 37",
"type": "boolean",
"default": true
},
"scan_channel_38": {
"title": "Configure Bluetooth scanning: Use channel 38",
"type": "boolean",
"default": true
},
"scan_channel_39": {
"title": "Configure Bluetooth scanning: Use channel 39",
"type": "boolean",
"default": true
},
"scan_filter_allow_listed": {
"title": "Type of Bluetooth sensors filtering",
"description": "If it's true, only the sensors in the list will pass through the filter, other sensors will be filtered out. If it's false, then all sensors will pass through the filter except those in the list.",
"type": "boolean",
"default": false
},
"scan_filter_list": {
"title": "List of sensors to filter.",
"description": "Type of filtering is set by scan_filter_allow_listed. If scan_filter_list is empty, then filtering is not active",
"type": "array",
"default": [],
"examples": [
[],
["F4:1F:0C:28:CB:D6"],
["F4:1F:0C:28:CB:D6", "F4:C6:46:2C:3E:B4"]
]
},
"coordinates": {
"title": "GPS-coordinates of the Gateway",
"type": "string",
"default": "",
"examples": [
""
]
},
"fw_update_url": {
"title": "URL of firmware update server",
"type": "string",
"default": "https://network.ruuvi.com/firmwareupdate",
"examples": [
"https://network.ruuvi.com/firmwareupdate"
]
}
},
"examples": [
{
"wifi_sta_config": {
"ssid": "",
"password": ""
},
"wifi_ap_config": {
"password": ""
},
"use_eth": false,
"eth_dhcp": true,
"eth_static_ip": "",
"eth_netmask": "",
"eth_gw": "",
"eth_dns1": "",
"eth_dns2": "",
"remote_cfg_use": false,
"remote_cfg_url": "",
"remote_cfg_auth_type": "no",
"remote_cfg_auth_bearer_token": "",
"remote_cfg_auth_basic_user": "",
"remote_cfg_auth_basic_pass": "",
"remote_cfg_refresh_interval_minutes": 0,
"use_http": true,
"http_url": "https://network.ruuvi.com/record",
"http_period": 10,
"http_user": "",
"http_pass": "",
"use_http_stat": true,
"http_stat_url": "https://network.ruuvi.com/status",
"http_stat_user": "",
"http_stat_pass": "",
"use_mqtt": false,
"mqtt_disable_retained_messages": false,
"mqtt_transport": "TCP",
"mqtt_data_format": "ruuvi_raw",
"mqtt_server": "test.mosquitto.org",
"mqtt_port": 1883,
"mqtt_prefix": "",
"mqtt_client_id": "",
"mqtt_user": "",
"mqtt_pass": "",
"lan_auth_type": "lan_auth_default",
"lan_auth_user": "Admin",
"lan_auth_api_key": "",
"auto_update_cycle": "regular",
"auto_update_weekdays_bitmask": 127,
"auto_update_interval_from": 0,
"auto_update_interval_to": 24,
"auto_update_tz_offset_hours": 3,
"ntp_use": true,
"ntp_use_dhcp": false,
"ntp_server1": "time.google.com",
"ntp_server2": "time.cloudflare.com",
"ntp_server3": "pool.ntp.org",
"ntp_server4": "time.ruuvi.com",
"company_use_filtering": true,
"company_id": 1177,
"scan_coded_phy": false,
"scan_1mbit_phy": true,
"scan_extended_payload": true,
"scan_channel_37": true,
"scan_channel_38": true,
"scan_channel_39": true,
"coordinates": "",
"fw_update_url": "https://network.ruuvi.com/firmwareupdate"
}
]
}Last updated