Hubble Network

https://hubble.com/docs/
Admin
Hubble Network provides a terrestrial and upcoming satellite network to connect off-the-shelf...
Tokens:149,816
Snippets:1,045
Trust Score:8.1
Update:1 week ago
Show doc for...
Tokens:
Raw
### Doctor output when setup is ready

Source: https://hubble.com/docs/guides/cli

Example output from a successful doctor run, showing valid credentials, Bluetooth, and Docker, with a skipped receiver check.

```text
✓ Credentials    valid, PROD
✓ Bluetooth      usage description present
✓ Docker         reachable
- Receiver       receiver image not pulled yet
First `sat scan` will pull it, which takes a minute.

Ready to go.  ·  3 ok  ·  1 skipped
```

--------------------------------

### Doctor output when setup fails

Source: https://hubble.com/docs/guides/cli

Example output from a doctor run with missing credentials and unavailable Docker, showing the fixes and a failure status.

```text
✗ Credentials    not set
Set both, or pass --org-id/--token:
export HUBBLE_ORG_ID=
export HUBBLE_API_TOKEN=
✓ Bluetooth      usage description present
✗ Docker         Docker is not available
Only `sat` commands need Docker.

Not ready.  ·  1 ok  ·  2 failed
```

--------------------------------

### Response Example: Active Devices

Source: https://hubble.com/docs/api-specification/get-billing-active-devices

Example JSON response for a successful request, showing the devices array with device_id, name, network_type, last_active, and the billing period start and end.

```json
{  
  "devices": [  
    {  
      "device_id": "string",  
      "name": "string",  
      "network_type": "terrestrial",  
      "last_active": 0  
    }  
  ],  
  "period_start": "2024-07-29T15:51:28.071Z",  
  "period_end": "2024-07-29T15:51:28.071Z"  
}  

```

--------------------------------

### C# HttpClient Request Example

Source: https://hubble.com/docs/api-specification/get-billing-active-devices

C# code example using HttpClient to send a GET request to the active-devices endpoint with Bearer token authorization.

```csharp
var client = new HttpClient();  
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.hubble.com/v1/org/:org_id/billing/active-devices");  
request.Headers.Add("Accept", "application/json");  
request.Headers.Add("Authorization", "Bearer <token>");  
var response = await client.SendAsync(request);  
response.EnsureSuccessStatusCode();  
Console.WriteLine(await response.Content.ReadAsStringAsync());  

```

--------------------------------

### Get Device Metrics - Success Response Example

Source: https://hubble.com/docs/api-specification/get-device-metrics

Example JSON response for a successful device metrics request. Shows the structure with buckets array and total counts for active, registered, and never active devices.

```json
{  
  "buckets": [  
    {  
      "timestamp": "2024-07-29T15:51:28.071Z",  
      "registered_devices": 0,  
      "active_devices": 0,  
      "never_active_devices": 0  
    }  
  ],  
  "total_active_devices": 0,  
  "total_registered_devices": 0,  
  "total_never_active_devices": 0  
}  

```

--------------------------------

### C# HTTP Client Request Example

Source: https://hubble.com/docs/api-specification/get-device-metrics

Example C# code using HttpClient to send a GET request to the device metrics endpoint. Includes Authorization header with Bearer token and prints the response.

```csharp
var client = new HttpClient();  
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.hubble.com/v1/org/:org_id/device_metrics");  
request.Headers.Add("Accept", "application/json");  
request.Headers.Add("Authorization", "Bearer <token>");  
var response = await client.SendAsync(request);  
response.EnsureSuccessStatusCode();  
Console.WriteLine(await response.Content.ReadAsStringAsync());  

```

--------------------------------

### C# HTTP client example for List Key Scopes

Source: https://hubble.com/docs/api-specification/list-key-scopes

Uses HttpClient to send a GET request to the key_scopes endpoint with Bearer token authorization.

```csharp
var client = new HttpClient();  
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.hubble.com/v1/org/:org_id/key_scopes");  
request.Headers.Add("Accept", "application/json");  
request.Headers.Add("Authorization", "Bearer <token>");  
var response = await client.SendAsync(request);  
response.EnsureSuccessStatusCode();  
Console.WriteLine(await response.Content.ReadAsStringAsync());  
```

--------------------------------

### C# Example: List Devices Request

Source: https://hubble.com/docs/api-specification/list-devices

C# code using HttpClient to send a GET request to the List Devices endpoint with Bearer token authorization.

```csharp
var client = new HttpClient();  
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.hubble.com/v2/org/:org_id/devices");  
request.Headers.Add("Accept", "application/json");  
request.Headers.Add("Authorization", "Bearer <token>");  
var response = await client.SendAsync(request);  
response.EnsureSuccessStatusCode();  
Console.WriteLine(await response.Content.ReadAsStringAsync());  
```

--------------------------------

### API Keys Response Example

Source: https://hubble.com/docs/api-specification/list-api-keys

A concrete example of a successful API keys response.

```json
{
  "keys": [
    {
      "key_id": "6ea53e36-b7fb-429f-8c2e-d536cab71089",
      "key_name": "Warehouse Inventory Sync",
      "created_at": 1704067200,
      "expires_at_seconds": 1767225600,
      "scopes": [
        "read-devices",
        "read-packets"
      ]
    }
  ]
}
```

--------------------------------

### Response example with actual values for List Key Scopes

Source: https://hubble.com/docs/api-specification/list-key-scopes

Example response showing two scopes: read-api-keys and read-devices with their display names.

```json
{  
  "scopes": [  
    {  
      "scope_id": "read-api-keys",  
      "display_name": "Read API Keys"  
    },  
    {  
      "scope_id": "read-devices",  
      "display_name": "Read Devices"  
    }  
  ]  
}  
```

--------------------------------

### GET /v2/org/:org_id/devices/:device_id

Source: https://hubble.com/docs/api-specification/get-device

This snippet documents the GET /v2/org/:org_id/devices/:device_id endpoint, including its path parameters, response schema, and example response.

```APIDOC
## GET /v2/org/:org_id/devices/:device_id

### Description
Return a specific registered device belonging to your organization.

### Method
GET

### Endpoint
https://api.hubble.com/v2/org/:org_id/devices/:device_id

### Parameters
#### Path Parameters
- **org_id** (uuid) - Required - Your organization ID
- **device_id** (uuid) - Required - The device ID

### Response
#### Success Response (200)
- **name** (string) - Required - Assigned name for the device (<= 250 characters)
- **id** (uuid) - Required - Primary UUID identifier for a registered device
- **created_ts** (int64) - Required - An UTC second-precision timestamp formatted as an integer
- **tags** (object) - Required - Tags are user-defined key/value pairs that can be attributed to a device. A device may have up to 10 tags. Custom tags: create your own tags with `key` length up to 32 characters and `value` length up to 128 characters. Platform tags: use Hubble-defined tags to organize devices. `_env` tag: `production` indicates if a device belongs to the live environment, and `sandbox` for the test environment. A device will always have an `_env` tag assigned.
- **encryption** (string) - Optional - Encryption mode configured for the device at registration. Possible values: [`AES-256-CTR`, `AES-128-CTR`, `AES-128-EAX`, `NONE`]
- **eid_rotation** (object) - Optional - Configuration for EID (Ephemeral ID) rotation on a device. EID rotation allows devices to use rotating ephemeral identifiers based on the specified counter source. When not specified, devices will use the UNIX_TIME counter source which relies on the device knowing an accurate epoch time. The DEVICE_UPTIME counter source enables EID rotation without requiring a real-time clock.
  - **counter_source** (string) - Optional - The counter source used for EID rotation. Possible values: [`UNIX_TIME`, `DEVICE_UPTIME`]
  - **period_exponent** (integer) - Optional - Base-2 exponent of the EID rotation period in seconds, used only with `encryption` of "AES-128-EAX" (IN100 protocol). Matches the IN100 hardware's configuration field. Must be between 10 (~17 minutes) and 15 (~9 hours) inclusive. Default value: 15
- **install_location** (object) - Optional - Fixed installation location of a device. To clear a previously set location, send lat/long of 0,0.
  - **lat** (double) - Required - Latitude in Decimal Degrees DDD.DDDDD° (>= -90 and <= 90)
  - **long** (double) - Required - Longitude in Decimal Degrees DDD.DDDDD° (>= -180 and <= 180)
  - **location_name** (string) - Optional - Human-readable label for the location (<= 500 characters)
- **most_recent_packet** (object) - Optional - Most recent packet metadata for different network types. The most recent packet value is only updated periodically.
  - **satellite** (object) - Optional - nullable
    - **timestamp** (double) - Optional - Unix timestamp of a recent satellite packet
    - **location** (object) - Optional - Location data from a recent satellite packet
      - **latitude** (double) - Required - Latitude in Decimal Degrees DDD.DDDDD° (>= -90 and <= 90)
      - **longitude** (double) - Required - Longitude in Decimal Degrees DDD.DDDDD° (>= -180 and <= 180)
  - **terrestrial** (object) - Optional - nullable
    - **timestamp** (double) - Optional - Unix timestamp of a recent terrestrial packet
    - **location** (object) - Optional - Location data from a recent terrestrial packet
      - **latitude** (double) - Required - Latitude in Decimal Degrees DDD.DDDDD° (>= -90 and <= 90)
      - **longitude** (double) - Required - Longitude in Decimal Degrees DDD.DDDDD° (>= -180 and <= 180)

#### Response Example
```json
{
  "name": "string",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_ts": 0,
  "tags": {
    "_env": "production"
  },
  "encryption": "AES-256-CTR",
  "eid_rotation": {
    "counter_source": "UNIX_TIME",
    "period_exponent": 15
  },
  "install_location": {
    "lat": 0,
    "long": 0,
    "location_name": "string"
  },
  "most_recent_packet": {
    "satellite": {
      "timestamp": 0,
      "location": {
        "latitude": 0,
        "longitude": 0
      }
    },
    "terrestrial": {
      "timestamp": 0,
      "location": {
        "latitude": 0,
        "longitude": 0
      }
    }
  }
}
```

### Error Responses
- **400** - Bad Request
- **500** - Internal Server Error
```

--------------------------------

### C# HTTP client request example

Source: https://hubble.com/docs/api-specification/get-recent-invoices

Example C# code using HttpClient to send a GET request to the invoices endpoint with Bearer token authentication.

```csharp
var client = new HttpClient();  
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.hubble.com/v1/org/:org_id/billing/invoices");  
request.Headers.Add("Accept", "application/json");  
request.Headers.Add("Authorization", "Bearer <token>");  
var response = await client.SendAsync(request);  
response.EnsureSuccessStatusCode();  
Console.WriteLine(await response.Content.ReadAsStringAsync());  
```

--------------------------------

### Python SDK usage example

Source: https://hubble.com/docs/guides/cli

Shows how to use the hubblenetwork SDK to create an Organization, register a device, iterate devices, and scan BLE packets. Note that the SDK does not read environment variables; credentials must be passed explicitly.

```python
from hubblenetwork import Organization, ble, decrypt

org = Organization(
org_id=os.environ["HUBBLE_ORG_ID"],
api_token=os.environ["HUBBLE_API_TOKEN"],
)

new_dev = org.register_device()           # returns a Device, with its key
for d in org.iter_devices():              # streams as pages arrive
print(d.id, d.name)

for pkt in ble.scan(timeout=5.0):
plaintext = decrypt(new_dev.key, pkt)
if plaintext:
print(plaintext.payload)
```

--------------------------------

### Bad Request error response (example)

Source: https://hubble.com/docs/api-specification/retrieve-organization-packets

Example error response for a Bad Request with a specific description: "'start' cannot be more than 30 days in the past".

```json
{  
  "code": 400,  
  "description": "'start' cannot be more than 30 days in the past",  
  "name": "Bad Request"  
}  

```

--------------------------------

### Success Response Example (Realistic)

Source: https://hubble.com/docs/api-specification/batch-update-devices

Example JSON response for a successful batch update with realistic device data, showing two devices with custom tags and empty most_recent_packet.

```json
{
  "devices": [
    {
      "id": "6ea53e36-b7fb-429f-8c2e-d536cab71089",
      "name": "Your Device 1",
      "created_ts": 1609459200,
      "tags": {
        "location": "warehouse-a"
      },
      "most_recent_packet": {}
    },
    {
      "id": "7fb64f47-c8ec-530e-9d3f-e647dbc8219a",
      "name": "Your Device 2",
      "created_ts": 1609459200,
      "tags": {
        "location": "warehouse-b"
      },
      "most_recent_packet": {}
    }
  ]
}
```

--------------------------------

### C# HTTP Client GET Device

Source: https://hubble.com/docs/api-specification/get-device

C# HTTP client example for making a GET request to the device endpoint. Requires a bearer token and accepts JSON responses.

```csharp
var client = new HttpClient();  
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.hubble.com/v2/org/:org_id/devices/:device_id");  
request.Headers.Add("Accept", "application/json");  
request.Headers.Add("Authorization", "Bearer <token>");  
var response = await client.SendAsync(request);  
response.EnsureSuccessStatusCode();  
Console.WriteLine(await response.Content.ReadAsStringAsync());  

```

--------------------------------

### Request Body Example (from schema)

Source: https://hubble.com/docs/api-specification/register-new-devices

Example JSON request body for registering devices. It specifies the number of devices, encryption type, and device names.

```json
{
  "n_devices": 1,
  "encryption": "AES-256-CTR",
  "names": [
    "my-device"
  ]
}
```

--------------------------------

### C# HTTP client request to get packet metrics

Source: https://hubble.com/docs/api-specification/get-packet-metrics

C# example using HttpClient to send a GET request to the packet metrics endpoint with Bearer token authorization.

```csharp
var client = new HttpClient();  
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.hubble.com/v1/org/:org_id/packet_metrics");  
request.Headers.Add("Accept", "application/json");  
request.Headers.Add("Authorization", "Bearer <token>");  
var response = await client.SendAsync(request);  
response.EnsureSuccessStatusCode();  
Console.WriteLine(await response.Content.ReadAsStringAsync());  

```

--------------------------------

### Success Response Example (Schema)

Source: https://hubble.com/docs/api-specification/batch-update-devices

Example JSON response for a successful batch update, showing the structure of the devices array with all fields.

```json
{
  "devices": [
    {
      "name": "string",
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "created_ts": 0,
      "tags": {
        "_env": "production"
      },
      "encryption": "AES-256-CTR",
      "eid_rotation": {
        "counter_source": "UNIX_TIME",
        "period_exponent": 15
      },
      "install_location": {
        "lat": 0,
        "long": 0,
        "location_name": "string"
      },
      "most_recent_packet": {
        "satellite": {
          "timestamp": 0,
          "location": {
            "latitude": 0,
            "longitude": 0
          }
        },
        "terrestrial": {
          "timestamp": 0,
          "location": {
            "latitude": 0,
            "longitude": 0
          }
        }
      }
    }
  ]
}
```

--------------------------------

### HTTP request example (C# HttpClient)

Source: https://hubble.com/docs/api-specification/retrieve-organization-packets

Example HTTP request to retrieve packets using C# HttpClient. Sends a GET request to https://api.hubble.com/v1/org/:org_id/packets with Accept and Authorization headers.

```csharp
var client = new HttpClient();  
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.hubble.com/v1/org/:org_id/packets");  
request.Headers.Add("Accept", "application/json");  
request.Headers.Add("Authorization", "Bearer <token>");  
var response = await client.SendAsync(request);  
response.EnsureSuccessStatusCode();  
Console.WriteLine(await response.Content.ReadAsStringAsync());  

```

--------------------------------

### Request body example for provisioning API key

Source: https://hubble.com/docs/api-specification/provision-api-key

JSON body for the POST request. Contains name, expires_at_seconds, and scopes array with read-api-keys, read-users, and read-devices.

```json
{
  "name": "string",
  "expires_at_seconds": 0,
  "scopes": [
    "read-api-keys",
    "read-users",
    "read-devices"
  ]
}
```

--------------------------------

### C# HttpClient Request Example

Source: https://hubble.com/docs/api-specification/get-api-metrics

Example C# code using HttpClient to send a GET request to the API metrics endpoint. Requires a Bearer token and Accept header. The response is printed to the console.

```csharp
var client = new HttpClient();  
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.hubble.com/v1/org/:org_id/api_metrics");  
request.Headers.Add("Accept", "application/json");  
request.Headers.Add("Authorization", "Bearer <token>");  
var response = await client.SendAsync(request);  
response.EnsureSuccessStatusCode();  
Console.WriteLine(await response.Content.ReadAsStringAsync());  

```

--------------------------------

### 200 Response Example (auto)

Source: https://hubble.com/docs/api-specification/list-users-in-organization

Example response for a successful request, showing a page of users with fields like user_id, email, and role.

```json
{  
  "users": [  
    {  
      "user_id": "string",  
      "email": "user@example.com",  
      "email_confirmed": true,  
      "first_name": "string",  
      "last_name": "string",  
      "created_at": 0,  
      "last_active_at": 0,  
      "role": "admin"  
    }  
  ]  
}  

```

--------------------------------

### Request Body Example (from schema)

Source: https://hubble.com/docs/api-specification/create-webhook-endpoint

Example request body for creating a webhook, containing url, max_batch_size, and name fields.

```json
{
  "url": "string",
  "max_batch_size": 100,
  "name": "string"
}
```

--------------------------------

### Build and flash the Zephyr continuous sample

Source: https://hubble.com/docs/network/satellite/quick-start

Build the Zephyr sat-continuous sample for the nrf54l15dk board, providing the base64 device key at build time, then flash it. The key is passed via `-DCONFIG_SAMPLE_HUBBLE_KEY`.

```shell
west build -b nrf54l15dk/nrf54l15/cpuapp . -- -DCONFIG_SAMPLE_HUBBLE_KEY=""
west flash
```

--------------------------------

### C# HttpClient example

Source: https://hubble.com/docs/api-specification/validate-api-key

C# code using HttpClient to send a GET request to the validate API key endpoint.

```csharp
var client = new HttpClient();  
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.hubble.com/v1/org/:org_id/check");  
request.Headers.Add("Accept", "application/json");  
request.Headers.Add("Authorization", "Bearer <token>");  
var response = await client.SendAsync(request);  
response.EnsureSuccessStatusCode();  
Console.WriteLine(await response.Content.ReadAsStringAsync());  

```
Tokens:
Raw