Configuration

Note

The majority of users will use Balena, so we’ll give examples in balena here. Configuring in a manually installed environment is broadly the same.

Add a service account

Using the name generated by balena when the device was added, create a dedicated service account by following these instructions.

Once you have the json file containing credentials on your computer, select your new device from the fleet and open a terminal (on main, not on the host OS) and do:

nano $GOOGLE_APPLICATION_CREDENTIALS

Then paste the contents of the credentials file. Press ctrl-x then y to save and exit. This file will persist over reboots of the device; you shouldn’t need to touch it again.

Open a terminal to the ‘main’ target and you can shell into the machine directly.

Add routine and configuration files

We’ll start with an empty routine file, which you can change later (see Routine files), and a basic configuration file.

mkdir -p /data/routines && echo "[]" > /data/routines/my-routine.json
mkdir -p /data/configurations && nano /data/configurations/my-configuration.json

Then paste in the following JSON (a basic configuration), update the values and save it:

{
  "gateway": {
    "installation_reference": "my-installation-reference", // change this to a meaningful value, eg "aventa-initial-deployment"
    "latitude": 0,
    "longitude": 0,
    "receiver_firmware_version": "unknown"
  },
  "nodes": {
    "1": {},
    "2": {},
    "3": {},
    "4": {},
    "5": {}  // Remove nodes if you know you don't need them
  },
  "measurement_campaign": {
    "label": "test-campaign",
    "description": "This field can be used to label and describe different measurement campaigns"
  }
}

Warning

You can store as many different configurations and routines as you want, but you should always save them somewhere in the /data/ folder, because it persists over restarts.

Set device variables

When you run the gateway, you’ll be able to able to specify a routine file and a configuration file. However, that makes for a lot of typing, especially when you’re trying to debug things.

To ease frustration, the best thing to do is to set these values as environment variables. Go to the “Device Variables” tab and add two variables, GATEWAY_ROUTINE_FILE and GATEWAY_CONFIG_FILE, whose values match the paths you set for the two files above.

Set device variables to change the default GATEWAY_ROUTINE_FILE and GATEWAY_CONFIG_FILE.

Check the installation

In the balena (or your own, for a manual installation) terminal, check by typing:

gateway --help

If the gateway is correctly installed, you should see this.

Tip

You can always use the $GATEWAY_CONFIG_FILE or $GATEWAY_ROUTINE_FILE to see the paths and their contents:

echo The config file is at $GATEWAY_CONFIG_FILE and it contains...
cat $GATEWAY_CONFIG_FILE