cyberwave-edge-core 0.0.26

The core component of the Cyberwave Edge Node

Cyberwave Edge Core

This Edge component acts as an orchestrator of your Cyberwave edge components.

Quickstart (Linux machines)

SSH into the device where you want to install the edge.

# Install the CLI (one time setup)
curl -fsSL https://cyberwave.com/install.sh | bash

# Use the CLI to complete the edge setup
sudo cyberwave edge install

The cyberwave-cli will ask you to log in with your Cyberwave credentials and then will proceed installing the cyberwave-edge-core on your edge device.

Don't have a Cyberwave account? Get one at cyberwave.com

Configuration

The edge core reads configuration from /etc/cyberwave/ (overridable via the CYBERWAVE_EDGE_CONFIG_DIR environment variable, which is set in the systemd unit):

File	Description
credentials.json	API token, workspace info
fingerprint.json	Device fingerprint
environment.json	Linked environment UUID

Of the files above, the core needs only the credentials.json file. You can easily populate it with the cyberwave-cli as described in the quickstart.

The fingerprint.json is populated by the core itself.

How the edge works

Once it's started (either via CLI or via service) the core does the following:

1. Checks if the credentials stored in credentials.json are valid
2. Connects to the backend MQTT and checks if the connection is up and running
3. Registers the edge device is running on, or updates its registration record. Each edge device is defined by a unique hardware fingerprint
4. Downloads the latest environment from the backend and resolves the twins linked to this edge fingerprint
5. Starts drivers for linked twins, with one special case for attached camera twins:
   • if a linked twin is a camera child twin (attach_to_twin_uuid) of another linked twin, edge-core does not start a dedicated driver for that camera child
   • edge-core passes camera child UUIDs to the parent driver via CYBERWAVE_CHILD_TWIN_UUIDS

Remote restart (via Edge REST API)

POST /api/v1/edges/{uuid}/restart-core publishes an MQTT command to:

edges/{edge_uuid}/command

with {"command":"restart_edge_core", ...} payload.

The running edge-core subscribes to that topic using the Cyberwave SDK and, when it receives the command, it:

1. Deletes cached twin JSON objects under the edge config directory
2. Stops/removes edge-managed driver containers and prunes stopped containers
3. Re-downloads the linked environment twins and starts drivers again

Writing compatible drivers

A Cyberwave driver is a Docker image that is capable of interacting with the device's hardware, sending and getting data from the Cyberwave backend. Every time the core starts a driver Docker image, the core does so by defining the following environment variables:

• CYBERWAVE_TWIN_UUID
• CYBERWAVE_API_KEY
• CYBERWAVE_TWIN_JSON_FILE
• CYBERWAVE_CHILD_TWIN_UUIDS (optional, comma-separated)

CYBERWAVE_CHILD_TWIN_UUIDS is present when the driver twin has attached camera child twins in the same linked set. Drivers can use this to discover and coordinate child twins without relying on extra camera selection prompts.

The Cyberwave twin JSON file is an absolute path to a JSON file. The JSON file is writable by the driver. It represents a complete twin object as well as its complete asset object. It represented in the same way that is it in the API, including the whole metadata field, schema and abilities. Twin reference here, Asset reference here.

As a driver, you can change the JSON file. The core will, when connectivity is present, sync it with the one in the backend.

When writing drivers, use the official Cyberwave SDK to communicate with the backend, as it will abstract a bunch of complexity in the MQTT handshake, REST API authentication, and more.

Once you wrote a driver, you can add its details in the twin's metadata (or the asset's metadata if you own it). Right now the edit is manual and directly in the metadata. To edit the metadata, you can switch to Advanced editing in the environment or in the asset editing.

Note: If you change the metadata on the asset, every twin created out of that asset from that moment on will have the same metadata as the asset, as the starting point

The driver object in the metadata looks like this:

"drivers": {
    "default": {
        "docker_image":"cyberwaveos/so101-driver", // this is either a public image on the Docker hub or on your own registry
        "version": "0.0.1", // this field is optional
        "params" : ["--network local", "--add-host host.docker.internal:host-gateway"] // this is also optional
    }
}

For an example, check how the camera driver handles the TWIN JSON file.

Passing environment variables to drivers (metadata["drivers"])

To inject environment variables into a driver container, use the params field with Docker's -e flag:

"drivers": {
  "default": {
    "docker_image": "cyberwaveos/go2-native-driver",
    "params": ["-e", "MY_VAR=value", "-e", "ANOTHER_VAR=value2"]
  }
}

Each -e must be its own element in the array, followed by the KEY=value string as the next element. This is equivalent to passing -e MY_VAR=value on the docker run command line.

This is useful for driver-specific configuration that varies per device, such as IP addresses, credentials, or feature flags that cannot be stored in the twin's edge_configs metadata.

Runtime configuration for drivers (metadata["edge_configs"])

Drivers and edge services should treat metadata["edge_configs"] as the source of truth for per-device runtime configuration. Edge identity should be stored at metadata["edge_fingerprint"] (not duplicated inside edge_configs).

Runtime access: The core passes the full twin JSON (including metadata) to every driver via the CYBERWAVE_TWIN_JSON_FILE environment variable. Drivers can read edge_configs from that file at startup to obtain per-device settings — for example, selecting the right camera source or IP address for the current machine. This is the recommended way to pass device-specific configuration to a driver without hardcoding values in the image.

• Type: object/dictionary
• Value: binding object (object)

Canonical shape:

"edge_fingerprint": "macbook-pro-a1b2c3d4e5f6",
"edge_configs": {
  "camera_config": {
    "camera_id": "front",
    "source": "rtsp://user:pass@192.168.1.20/stream",
    "fps": 10,
    "resolution": "VGA",
    "camera_type": "cv2"
  }
}

Field notes:

• edge_fingerprint (recommended): fingerprint of the edge currently serving this twin (top-level metadata field).
• camera_config (recommended): per-device camera/runtime config consumed by edge drivers.
• Do not store edge_uuid, registered_at, last_sync, last_ip_address, or status_data inside edge_configs.

Backward compatibility:

• Older records may still use the legacy map shape (edge_configs[fingerprint] = {...}).
• Older records may store camera settings in cameras[0] or as top-level fields.
• New writers should always write to camera_config.
• Do not rely on PUT /api/v1/edges/{uuid}/twins/{twin_uuid}/camera-config; it is deprecated. Update twin metadata instead.

Advanced usage

Manual install and usage

# Install the registry signing key:

curl -fsSL "https://packages.buildkite.com/cyberwave/cyberwave-edge-core/gpgkey" | gpg --dearmor -o /etc/apt/keyrings/cyberwave_cyberwave-edge-core-archive-keyring.gpg

# Configure the source:

echo -e "deb [signed-by=/etc/apt/keyrings/cyberwave_cyberwave-edge-core-archive-keyring.gpg] https://packages.buildkite.com/cyberwave/cyberwave-edge-core/any/ any main\ndeb-src [signed-by=/etc/apt/keyrings/cyberwave_cyberwave-edge-core-archive-keyring.gpg] https://packages.buildkite.com/cyberwave/cyberwave-edge-core/any/ any main" > /etc/apt/sources.list.d/buildkite-cyberwave-cyberwave-edge-core.list

# Run all startup checks (validate token, MQTT, devices, environment)
cyberwave-edge-core

# Show current credential, token, MQTT, and device status
cyberwave-edge-core status

# Show version
cyberwave-edge-core --version

Other env vars

To run against another env:

export CYBERWAVE_ENVIRONMENT="yourenv"
export CYBERWAVE_BASE_URL="https://yourbaseurl"
cyberwave-edge-core

Or from the CLI

sudo CYBERWAVE_ENVIRONMENT="yourenv" CYBERWAVE_BASE_URL="https://yourbaseurl" cyberwave edge install