Documentation

1. Obtain a Hublink account and hardware (see Pricing).
2. Integrate the Hublink firmware (see Hublink Node Library )
3. Start uploading files and view the progress on your Hublink Dashboard.
4. Batch download data or use the Hublink Client Library for syncing.

Storage Settings

• AWS Access Key ID: AWS credential for S3 access
• AWS Secret Access Key: AWS credential for S3 access
• S3 Bucket Name: Destination bucket for file storage

Gateway Settings

• Max File Size: Maximum allowed file size in bytes
• Timezone: Timezone (e.g., America/New_York)
• Device Filter by Name: Device name should include this string, cannot be blank

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 is used to authenticate the gateway with 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.

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.

The Hublink node uses a meta.json file on the SD card to configure node behavior and store metadata. The file uses JSON format:

{
  "hublink": {
    "advertise": "HUBLINK",
    "advertise_every": 300,
    "advertise_for": 30,
    "try_reconnect": true,
    "reconnect_attempts": 3,
    "reconnect_every": 30,
    "upload_path": "/FED",
    "append_path": "subject:id/experimenter:name",
    "disable": false
  },
  "subject": {
    "id": "mouse001",
    "strain": "C57BL/6",
    "strain_options": [
      "C57BL/6",
      "BALB/c",
      "129S1/SvImJ",
      "F344",
      "Long Evans",
      "Sprague Dawley"
    ],
    "sex": "male",
    "sex_options": [
      "male",
      "female"
    ]
  },
  "experimenter": {
    "name": "john_doe"
  },
  "device": {
    "id": "046"
  },
  "fed": {
    "program": "Classic",
    "program_options": [
      "Classic",
      "Intense",
      "Minimal",
      "Custom"
    ]
  }
}

Hublink Settings

The settings below modify the Hublink node behavior. These settings take effect at hublink.begin() but can be overridden at runtime (refer to the HublinkAdvanced.ino sketch).

Device Identification

The device.id field provides a unique identifier for your node that appears in the dashboard. This helps distinguish between multiple nodes in your experiment.

Custom Metadata

You can add any additional JSON objects to track metadata about your experiment. The example above shows:

• Subject information (ID, strain, sex)
• Predefined options for strain and sex selection
• Program settings with available options
• Any other relevant metadata specific to your experiment

The Hublink library provides several key functions for managing BLE communication and file transfer:

sync(uint32_t temporaryConnectFor = 0)

Manages BLE advertising and connection cycles. Returns true if a connection was established.

• temporaryConnectFor: Optional duration in seconds to override the default advertising period
• Returns: boolean indicating if connection was successful

sleep(uint64_t seconds)

Puts the ESP32 into light sleep mode for the specified duration to conserve battery.

setBatteryLevel(uint8_t level)

Sets the battery level for the node characteristic. Range 0-255 (0 indicates not set).

setAlert(const String &alert)

Sets an alert message that will be synced to the cloud. The user must persist the alert in their sketch—it is automatically cleared after the hublink.sync() completes. Alerts can also be cleared in the dashboard by a user.

Hublink uses file name and file size to determine if a file needs to be uploaded (or re-uploaded) to the cloud. Some common issues to be aware of:

• Overwriting files byte-for-byte: If a file is overwritten byte-for-byte, the file size will not change, and Hublink will not upload the file again.
• Large files: If a file is large, the upload time will be proportional to the file size, which may cause delays in data transfer and impacts battery life.

Files in Amazon S3 are organized according to the upload_path and optional append_path settings. The resulting file structure is:

bucket_name/
        ├── upload_path/               # From hublink.upload_path
        │   ├── append_path/           # From hublink.append_path reference
        │   │   └── filename.csv       # Actual files
        │   └── another_path/
        └── ...

Path Construction

The append_path field supports multiple nested JSON values separated by forward slashes. The path is constructed as follows:

1. Starts with upload_path
2. Appends each value specified in append_path if it exists and is not empty
3. Skips any missing or empty values
4. Sanitizes the path to ensure it's valid for S3 storage:
   • Allows alphanumeric characters (a-z, A-Z, 0-9)
   • Allows hyphen (-), underscore (_), plus (+), period (.)
   • Removes duplicate slashes
   • Removes trailing slashes

Path Construction Examples

bucket/
        └── FED/
            └── mouse001/
                └── data.csv

bucket/
        └── FED/
            └── mouse001/
                └── john_doe/
                    └── data.csv