Gateway Configuration

All gateways should be pre-configured — it is unlikely you will need to make any changes. The following information is provided for reference or troubleshooting purposes.

Gateway settings can be updated or data can be retrieved using a USB drive. If you need to replace the removeable media drive, follow these steps:

1. Format the drive with a compatible filesystem (e.g., ext4, FAT32)
2. Rename the drive to “HUBLINK”
3. Create a hublink.json file in the root of the drive with the configuration:

{
  "secret_url": "https://hublink.cloud/<secret_url>",
  "gateway_name": "Gateway1"
}

The secret URL identifies your account to the cloud service. The gateway name will automatically have a unique identifier appended to it based on the device’s MAC address to make it easier to identify on the dashboard.

Need Help Formatting?

Use our Hublink Card Formatter tool to safely format SD cards for both nodes and gateways. Includes safety checks and automatic configuration.

Enrollment (v2 image)

On first boot a gateway running the v2 image presents the secret URL once and receives its own token, which it uses for every later call instead of the secret URL. The gateway then shows as enrolled on the dashboard’s Settings page. If the token is revoked there, the gateway re-enrolls automatically on its next cycle. Once every gateway on an account is enrolled, an administrator can require tokens, after which the secret URL alone no longer grants access.

The v2 image also verifies each upload (size and checksum are sent to the cloud, which compares them with what S3 stored), refreshes its short-lived credentials before they expire, and never deletes a local file the cloud has not confirmed.

Offline Mode

Gateways will automatically enter offline mode if they are unable to connect to the cloud service. This is useful for situations where the gateway is in a remote location or behind a firewall. Data will be stored on the gateway until it is able to reconnect to the cloud service.

Status endpoint

http://<gateway>:5000/status reports connectivity, the gateway name, the contract version, whether it is enrolled, and any active errors by category (ble, file_manager, api, s3). It does not reveal the secret URL.

Rings

Gateways run a pinned image: the fleet runs the stable tag and one lab gateway runs canary. A release is promoted to stable after the canary has run it for a week with no re-uploads and no api errors. Gateways no longer update themselves; the lab pulls the new tag deliberately.