Configuration with json

Could anyone help with how to download the current setting file and upload the modified setting file?

I read from Ruuvi documentation that Ruuvi Gateway is configured by gw_cfg_default.json. This file could be read/write to by HTTP. However, the documentation does not tell to what address/location/URL to send or query the json file. Could anyone help?


The remote configuration through JSON is a feature that we’ll introduce in v1.12 release. We’re currently testing a release candidate and are aiming to release the update in September. You can install the development releases in GUI by using Artifacts of ruuvi_gateway_esp-PR #717 : /build [Jenkins] as the update URL.

The documentation is a work in progress, here is the JSON specification: The example JSON object is in the bottom.

The configuration supports both Gateway-specific and general configuration,

If you specify a folder name, it will first attempt to read the configuration file for this Gateway from <GW_MAC>.json (for example, AABBCCDDEEFF.json). If that file fails, an attempt will be made to read the overall configuration from gw_cfg.json.

Also, the configuration file can be generated dynamically by the server, for this the server must analyze the HTTP header 'ruuvi_gw_mac', which contains MAC address in the format XX:XX:XX:XX:XX:XX.

Server to download configuration from is defined in this screen after firmware update:

The polling interval of configuration is defined by “remote_cfg_refresh_interval_minutes”: 0.

If you’re planning to place a large order, we can configure the Gateways at factory to use the remote configuration URL by default at boot.

Great, thanks a lot for your help.
I have one more question related to the configuration: If I want to use Ruuvi tags together with third party BLE sensors (for example some iBeacons)with Ruuvi Gateway, I could make the json setting as below, couldn’t I?

“company_use_filtering”: true,
“company_id”: [1177, 76],
“scan_coded_phy”: false,

Or do I have to turn off the Ruuvi Gateway filter and filter the mac addresses on the relay server?

The company ID does not support array, I’m not sure what exactly would happen but it would not work to filter two companies.

You need to put "company_use_filtering": false and then filter on the backend to receive payloads with two different manufacturer IDs.

Thanks again Otso for your help. Two more questions:

  1. Is it possible to add “filter by company_ids” (an array of company ids) in the future?
  2. Is it possible to edit this configuration .json file locally? and how? So far I could only find the documentation to configure via web-UI.

Probably not, the filtering is done on Bluetooth chip level and that chip has really constrained resources.

We are considering adding an allowlist of tags, that could allow user to configure specific tags per gateway to send.

You need to put the JSON to server which the Gateway can access, any text editor will do for editing. The Gateway will then try to download the configuration.

Hello, Otso. I am on ruuvi gateway firmware 1.24.4. I still have problem with update the configuration via HTTP.
According to this documentation: Gateway configuration - docs (
I set up a simple local HTTP server with python http.server at port 8080 and set the correct firewall rules.
I put two json files in the directory with the name: <gw_mac>.json and gw_cfg.json
When I set from GUI - Automatic Configuration Download the url and pressed download. It reported me

Failed to get gw_cfg.json from the remote server.
Status: 503 (Service Unavailable)

But both the server and wireshark confirms the succesful http request and reply:

I too had confirmed from another PC’s browser, that I could get the json from by:

Actually ruuvi gateway did not even request for gw_cfg.json when I had correct <ruuvi_mac>.json at the directory. I tried to remove <ruuvi_mac>.json, ruuvi gateway did request for gw_cfg.json, and there was successful respond, but I got the same 503 error.

Then I tried to send HTTP request (via python and POSTMAN) to read and write the configuration files. But again I had no luck.
I sent HTTP GET/POST to Ruuvi gateway via “/ruuvi.json” api. However, I kept get 401 error. I tried both “basic auth” and “bear token”, but none of them worked. “bear token” worked on “/history” though.

Could you give some help? (BTW, Ruuvi has great documentation for developers, thanks a lot!)

@TheSomeMan Please take a look at the above problem

Hi @Siyuan,

The most likely cause of error 503 when downloading gw_cfg.json from the remote server is that the gw_cfg.json has the wrong format.
Please check the following:

  1. gw_cfg.json must begin with the character ‘{’
  2. gw_cfg.json must be a valid JSON
  3. ‘use_remote_cfg’ in gw_cfg.json must be ‘true’

When you connect Gateway to a PC via USB, it creates a serial port (COM-port) for logging, so you can connect to this serial port with an application like Putty (or similar), look at the logs, and see the cause of the problem.

@Alexey_Skvortsov Thanks you for your reply. My json was valid. However, I only had field
{“coordinates”: “12.34 56.78”}. Should I have every settings for json? When I added:
{“coordinates”: “12.34 56.78”, “use_remote_cfg”: ture}
gateway lost it’s static IP configuration. I had to poke the pin and use Wi-Fi to get into the gateway.

@Siyuan Sorry for the inconvenience, it’s a bug. The static IP configuration should not be lost after downloading the configuration from the remote server. It will be fixed in the next release (Static IP configuration is lost after downloading an empty configuration from a remote server · Issue #648 · ruuvi/ruuvi.gateway_esp.c · GitHub).
Here is the minimal configuration for Gateway configured with DHCP enabled:

{"remote_cfg_use": true, "remote_cfg_url": "http://IP:PORT/", "remote_cfg_refresh_interval_minutes": 1}

You can use the following workaround:

  1. Create a specific <ruuvi_mac>.json for your gateway
  2. Configure static IP in <ruuvi_mac>.json like this:
{"remote_cfg_use": true, "remote_cfg_url": "http://IP:PORT/", "remote_cfg_refresh_interval_minutes": 1, "use_eth": true, "eth_dhcp": false,"eth_static_ip": "","eth_netmask": "","eth_gw": "","eth_dns1": ""}

Wonderful. Thanks a lot. The work around worked. Great support from Ruuvi as usual. :+1:

I am encountering another problem though: “Nonce” field from the payload is gone. I am not sure how did it happen. Was it caused by I updated the setting via http with only “coordinates”? I resetted the gateway by press 5s reset button/pin. And reconfigured by web-UI. But there is no “Nonce” field from the payload. The documentation for the payload schema showed “Nonce” was required field. Is it removed from firmware all together or there was a new bug?

Update: it turns out /history api won’t give Nonce field. But from serial terminal, Nonce field was indeed there in the payload.

PS. I couldn’t find the release notes for each firmware(from ruuvi’s github), could you point it out?

Yes, /history API is a bit different, I added documentation for it:

PS. I couldn’t find the release notes for each firmware(from ruuvi’s github), could you point it out?

You can find the release notes on github: Releases · ruuvi/ruuvi.gateway_esp.c · GitHub

Thanks a lot Alexey!