> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyberwave.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Building Edge-to-Cloud VLM Pipelines with Cyberwave
> Develop an edge-to-cloud VLM pipeline for real-time visual inspection and automated safety monitoring.
**Stack:** Python, VLM, Edge Devices, Workflows
## Video Tutorial
***
## Overview
In this tutorial, you will learn how to integrate physical hardware with Cyberwave and deploy an autonomous safety sentinel powered by Vision Language Models.
By the end of this guide, you will be able to:
* **Connect:** Turn your local computer (Edge Device) into a smart camera node
* **Stream:** Send live video securely from your location to the Cyberwave cloud
* **Analyze:** Use AI to "look" at the video and answer questions like "Is the person wearing a helmet?"
* **Automate:** Trigger real-world actions (like sending an email) based on what the AI sees
To demonstrate these capabilities, we will build an **"Active Safety Officer"** for PPE compliance and industrial safety. While we focus on safety gear detection, this architecture is **agnostic** and can be applied to any **visual inspection task**.
### Building an Active Safety Officer
In high-stakes manufacturing environments, relying on manual surveillance for safety compliance is scalable only until it fails. In this tutorial, we will transform a standard webcam into an **"Active Safety Officer."** Instead of just recording footage, your camera will automatically detect if a worker is wearing the correct safety gear (PPE) and send an alert if they aren't.
We will build this system using the **[Cyberwave Edge SDK](https://github.com/cyberwave-os/cyberwave-edge-python)** and a **Vision Language Model (VLM)** workflow.
***
## Technical Overview
The Cyberwave stack decouples hardware from application logic and intelligence.
### Architecture
This tutorial rests on three architectural pillars:
Connect a physical edge device (e.g., webcam) to Cyberwave using the **[Python Edge SDK](https://github.com/cyberwave-os/cyberwave-edge-python)**. This streams low-latency visual data to a Digital Twin via Cyberwave's WebRTC and MQTT infrastructure.
Develop an automated Cyberwave **Workflow** to fetch live visual data and inject it into a Gen AI model.
Use a **VLM** (Vision-Language-Model) or **VLA** (Vision-Language-Action) model to process this data and automate decision-making with zero manual intervention.
### Components
* **[Edge Device](/concepts/edge-devices):** This is your physical hardware. In this tutorial, your **Laptop** and its **Webcam** act as the Edge Device. It sits in the real world, captures video, and sends it to the cloud via the Cyberwave SDK.
* **[Digital Twin](/concepts/digital-twins):** A virtual replica of your physical device that lives in the Cyberwave dashboard. When your Edge Device comes online, it syncs with this Digital Twin, allowing you to see the video feed and control the device remotely from your browser.
* **[Workflow](/concepts/workflows):** An event-driven serverless function that chains: Fetch Frame → VLM Inference → Boolean Logic → Trigger Action
***
## Prerequisites
Before starting this tutorial, ensure you have:
* Linux/macOS machine with a USB Webcam
* Python 3.9 or higher
* `pip` installed (Python package manager)
* `git` installed
* A Cyberwave Account ([Request Early Access](https://cyberwave.com/request-early-access))
* API Token from your dashboard (more details in the following steps)
***
## Phase 1: Connect the Edge Infrastructure
**Goal:** Connect your edge device (your physical hardware) to Cyberwave and ingest visual data into a Digital Twin.
### Step 1.1: Install the SDK
We utilize the [`cyberwave-edge-python` SDK](https://github.com/cyberwave-os/cyberwave-edge-python) to handle the hardware abstraction layer (HAL) and the network handshake between your physical camera and Cyberwave.
Open your terminal and run the following commands:
```bash theme={null}
# 1. Clone the Python edge client
git clone https://github.com/cyberwave-os/cyberwave-edge-python.git
cd cyberwave-edge-python
# 2. Create a virtual environment (Recommended for isolation)
python3 -m venv venv
source venv/bin/activate
# 3. Install dependencies
pip install -e .
```
### Step 1.2: Provision the Digital Twin
In the Cyberwave Dashboard, create a Digital Twin to represent your edge node:
1. Create a **New Project** and **Environment**.
2. **Add a Scene Object** to the environment to create a new twin.
3. **Choose the specific asset** from the Catalog and configure it with these details:
* **Asset Type:** Standard Camera
* **Name:** PPE Sentinel
**Critical:** Copy the **Twin UUID** generated for this asset. You will need it immediately.
Hover over the three dots of the asset in the sidebar, and click on **"Copy Twin UUID"**.
*(Note: If you do not see the three dots, your sidebar might be too narrow. Click and drag the edge of the sidebar to expand it.)*
4. Navigate to **Settings > API Keys** and generate a new API Token.
### Step 1.3: Configure the Edge Environment (`.env`)
Return to your local terminal and configure the environment to authenticate with the Twin.
1. Create the configuration file:
```bash theme={null}
cp .env.example .env
nano .env
```
2. Configure the `.env` file with the following variables:
| Variable | Value/Description |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CYBERWAVE_TOKEN` | **\** Your unique API authentication token. Get this from the Cyberwave Dashboard under Settings > API Keys. |
| `CYBERWAVE_TWIN_UUID` | **\** The UUID of the specific Digital Twin this device connects to. Copy this from the Twin's page in your Dashboard. Hover over the three dots of the asset in the sidebar, and click on **"Copy Twin UUID"**. *(Note: If you do not see the three dots, your sidebar might be too narrow. Click and drag the edge of the sidebar to expand it.)* |
| `CAMERA_ID` | **\** The hardware index of the camera. - Use `0` for the default laptop webcam - Use `1` or `2` for external USB cameras |
| `CAMERA_FPS` | `10` Frames Per Second. Controls video smoothness vs. bandwidth usage. 10 is a standard balance for monitoring. |
| `LOG_LEVEL` | `INFO` Sets the verbosity of the logs in your terminal. Options: DEBUG, INFO, WARNING, ERROR. |
#### Sample .env Configuration
```bash theme={null}
# Cyberwave API Configuration
CYBERWAVE_TOKEN=
# Device Configuration
CYBERWAVE_TWIN_UUID=
# Camera Configuration
CAMERA_ID=0
CAMERA_FPS=10
# Logging
LOG_LEVEL=INFO
```
### Step 1.4: Activate the Edge Stream
Start the daemon. The SDK will initiate an MQTT control channel and establish the WebRTC signaling path.
```bash theme={null}
cyberwave-edge
```
### Step 1.5: Verify Logs
Check your terminal output to verify the connection:
```bash theme={null}
Configuration loaded for the edge device
Connected to the MQTT broker
Edge service is running
```
If you see these messages, your edge device is successfully connected!
### Step 1.6: Verify the Stream
To confirm data ingestion, return to your Cyberwave Environment and "turn on" the camera in the interface. You should see live video frames streaming from your edge device directly into the Digital Twin.
***
## Phase 2: Configure the Workflow
**Goal:** Build a serverless logic flow that acts on visual data without writing backend code.
We will use Cyberwave Workflows to create a **"Fetch-Analyze-Act"** loop.
### Workflow Basics
When configuring nodes, you can set inputs using:
* **Fixed Value:** Hard-coded input parameters
* **Reference Another Node:** Use the output of a previous node as input
* **Expression:** Use templates with references to node outputs
### Step 2.1: Initialize the Workflow
1. Navigate to the **Workflows** tab in Cyberwave.
2. Click **Create Workflow** and name it `PPE-Compliance-Audit`.
3. **Trigger:** Select a **Schedule Trigger**. Set it to run every **1 minute**.
### Step 2.2: Data Ingestion Node
From the **Node Library → Actions**, add a **"Data Source"** node.
**Function:** Fetches the latest sensor data (images) from the USB webcam connected to the Twin.
**Configuration:**
* **Connection:** Connect this node to the **Schedule** node by dragging the pointer from one node to another.
* **Data Source Type:** Twin Image
* **Select Digital Twin:** Choose the `PPE Sentinel` twin created in Phase 1
* **Output Used:** We will utilize the `Image URL` output generated by this node in the next node (**intelligence node**).
### Step 2.3: Intelligence Node (VLM Integration)
From the **Node Library → Actions**, add a **"Call Models"** node.
**Function:** Abstracts the complexity of encoding inputs and calling AI models. It passes visual data to the VLM to analyze violations based on our prompt.
**Configuration:**
* **Connection:** Connect this node to the **Data Source** node by dragging the pointer from one node to another.
* **Select Model:** VLM Model
* **Prompt \[Fixed Value]:** Copy the following strict logic prompt:
```
You are an AI Industrial Safety Officer responsible for auditing video frames from a manufacturing facility. Your top priority is strict adherence to Personal Protective Equipment (PPE) guidelines. You must analyze images objectively and output machine-readable boolean results.
Analyze this image for PPE compliance.
1. DETECTION TARGETS:
- Scan for any person in the frame.
- If a person is found, check for:
A) Headgear (Hard hat, helmet, or baseball cap).
B) High-Visibility Torso Wear (Safety vest, bright jacket, or hoodie).
2. COMPLIANCE LOGIC:
- If NO person is visible: The area is safe. Result = true.
- If a person is visible AND wearing BOTH Headgear AND Torso Wear: The worker is compliant. Result = true.
- If a person is visible BUT is missing EITHER Headgear OR Torso Wear: The worker is non-compliant. Result = false.
3. OUTPUT FORMAT:
- Do not provide explanations, descriptions, or reasoning.
- Output ONLY a single lowercase string: "true" or "false".
```
* **Image URL \[Reference Node]:** Select the `Data Source` node and map its `Image URL` output (discussed in the previous step) to this field
* **Output Used:** We will use the `Result` variable (string format) output generated by this node in the next node (**conditional node**).
### Step 2.4: Conditional Branch Node
From the **Node Library → Actions**, add a **"Conditionals"** node.
**Function:** Parses the VLM output. If the condition is met (Violation Detected), the workflow proceeds; otherwise, it ends.
**Configuration:**
* **Connection:** Connect this node to the **Call Models** node by dragging the pointer from one node to another.
* **Comparison Operator:** Equal
* **Left Side Value \[Reference Node]:** Select the `Call Models` node and its `Result` output
* **Right Side Value \[Fixed Value]:** `false`
* **Save the Configuration:** Save the logic configuration to ensure the changes are saved.
**Logic:** The workflow continues only if the VLM returns `false` (indicating a safety violation).
### Step 2.5: Email Notification Node
From the **Node Library → Actions**, add a **"Send Emails"** node.
**Function:** Dispatches an alert when the conditional branch is triggered.
**Configuration:**
* **Connection:** Connect this node to the **Conditional Branch** node by dragging the pointer from one node to another.
* **To Email:** \[Your Escalation Email Address]
* **Subject:** `PPE Compliance Violation`
* **Body:** `There is a PPE violation detected in Zone X. Please investigate.`
### Step 2.6: Activate the Workflow
Click **Activate** to deploy the workflow configuration. This process automatically validates your workflow logic, ensuring it can run correctly and alerting you to any configuration errors before deployment.
Your workflow is now live and will run every minute to check for PPE compliance!
***
## Phase 3: Validate and Test
With the workflow active, it is time to physically validate the system.
### Pre-flight Check
Ensure the following before testing:
* ✅ The `cyberwave-edge` service is running in your terminal.
* ✅ The Workflow is **Active** in the dashboard.
* ✅ You can see live video in the Cyberwave Digital Twin interface.
### Test Case A: The "Safe" Worker
Put on your "Hard Hat" (baseball cap) and "Vest" (bright jacket).
Stand in front of the camera.
Wait for the scheduled 1-minute trigger (or trigger manually).
* The VLM analyzes the frame.
* Returns `"true"`.
* **NO email is sent** ✅
### Test Case B: The Violation
Remove the baseball cap (Missing Hard Hat). Keep the jacket on.
Stand in front of the camera.
Wait for the scheduled trigger.
1. VLM analyzes the frame and detects the jacket, but no hat.
2. Returns `"false"`.
3. Workflow enters the "Violation" branch.
4. **Inbox Check:** You receive an email notification within seconds.
***
## Conclusion
By decoupling the hardware (Phase 1) from the intelligence (Phase 2), you have built a solution that is **robust, scalable, and upgradeable**. You didn't write complex computer vision code to detect "hats"; you simply asked a VLM to do it for you.
This is the power of the **Cyberwave Industrial AI stack**.
***
## Troubleshooting
**Solution:**
* Verify your `CYBERWAVE_TOKEN` is correct
* Check that the `CYBERWAVE_TWIN_UUID` matches your Digital Twin
* Check logs with `LOG_LEVEL=DEBUG`
**Solution:**
* Verify camera permissions on your OS
* Try different `CAMERA_ID` values (0, 1, 2)
* Restart the `cyberwave-edge` service
**Solution:**
* Ensure the workflow is **Activated** (not just saved)
* Check the schedule trigger configuration
* Manually trigger the workflow to test
**Solution:**
* Check the image quality in the Digital Twin viewer
* Adjust the prompt for your specific use case
* Increase `CAMERA_FPS` for better image quality
* Ensure proper lighting in the camera view
**Solution:**
* Check your spam/junk folder
* Verify the email address in the workflow configuration
* Test with a different email address
***
## Related
Automate robot operations with visual workflows
Register and deploy AI models
Connect physical hardware to Cyberwave
***
## Technical Overview
The Cyberwave stack decouples hardware from application logic and intelligence.
### Architecture
This tutorial rests on three architectural pillars:
***
## Phase 2: Configure the Workflow
### Workflow Basics
When configuring nodes, you can set inputs using:
* **Fixed Value:** Hard-coded input parameters
* **Reference Another Node:** Use the output of a previous node as input
* **Expression:** Use templates with references to node outputs
### Step 2.1: Initialize the Workflow
1. Navigate to the **Workflows** tab in Cyberwave.
2. Click **Create Workflow** and name it `PPE-Compliance-Audit`.
3. **Trigger:** Select a **Schedule Trigger**. Set it to run every **1 minute**.
### Step 2.2: Data Ingestion Node
From the **Node Library → Actions**, add a **"Data Source"** node.
**Function:** Fetches the latest sensor data (images) from the USB webcam connected to the Twin.
**Configuration:**
* **Connection:** Connect this node to the **Schedule** node by dragging the pointer from one node to another.
* **Data Source Type:** Twin Image
* **Select Digital Twin:** Choose the `PPE Sentinel` twin created in Phase 1
* **Output Used:** We will utilize the `Image URL` output generated by this node in the next node (**intelligence node**).
### Step 2.3: Intelligence Node (VLM Integration)
From the **Node Library → Actions**, add a **"Call Models"** node.
**Function:** Abstracts the complexity of encoding inputs and calling AI models. It passes visual data to the VLM to analyze violations based on our prompt.
**Configuration:**
* **Connection:** Connect this node to the **Data Source** node by dragging the pointer from one node to another.
* **Select Model:** VLM Model
* **Prompt \[Fixed Value]:** Copy the following strict logic prompt:
```
You are an AI Industrial Safety Officer responsible for auditing video frames from a manufacturing facility. Your top priority is strict adherence to Personal Protective Equipment (PPE) guidelines. You must analyze images objectively and output machine-readable boolean results.
Analyze this image for PPE compliance.
1. DETECTION TARGETS:
- Scan for any person in the frame.
- If a person is found, check for:
A) Headgear (Hard hat, helmet, or baseball cap).
B) High-Visibility Torso Wear (Safety vest, bright jacket, or hoodie).
2. COMPLIANCE LOGIC:
- If NO person is visible: The area is safe. Result = true.
- If a person is visible AND wearing BOTH Headgear AND Torso Wear: The worker is compliant. Result = true.
- If a person is visible BUT is missing EITHER Headgear OR Torso Wear: The worker is non-compliant. Result = false.
3. OUTPUT FORMAT:
- Do not provide explanations, descriptions, or reasoning.
- Output ONLY a single lowercase string: "true" or "false".
```
* **Image URL \[Reference Node]:** Select the `Data Source` node and map its `Image URL` output (discussed in the previous step) to this field
* **Output Used:** We will use the `Result` variable (string format) output generated by this node in the next node (**conditional node**).
### Step 2.4: Conditional Branch Node
From the **Node Library → Actions**, add a **"Conditionals"** node.
**Function:** Parses the VLM output. If the condition is met (Violation Detected), the workflow proceeds; otherwise, it ends.
**Configuration:**
* **Connection:** Connect this node to the **Call Models** node by dragging the pointer from one node to another.
* **Comparison Operator:** Equal
* **Left Side Value \[Reference Node]:** Select the `Call Models` node and its `Result` output
* **Right Side Value \[Fixed Value]:** `false`
* **Save the Configuration:** Save the logic configuration to ensure the changes are saved.
**Logic:** The workflow continues only if the VLM returns `false` (indicating a safety violation).
### Step 2.5: Email Notification Node
From the **Node Library → Actions**, add a **"Send Emails"** node.
**Function:** Dispatches an alert when the conditional branch is triggered.
**Configuration:**
* **Connection:** Connect this node to the **Conditional Branch** node by dragging the pointer from one node to another.
* **To Email:** \[Your Escalation Email Address]
* **Subject:** `PPE Compliance Violation`
* **Body:** `There is a PPE violation detected in Zone X. Please investigate.`
### Step 2.6: Activate the Workflow
Click **Activate** to deploy the workflow configuration. This process automatically validates your workflow logic, ensuring it can run correctly and alerting you to any configuration errors before deployment.
***
## Phase 3: Validate and Test
With the workflow active, it is time to physically validate the system.
### Pre-flight Check
Ensure the following before testing:
* ✅ The `cyberwave-edge` service is running in your terminal.
* ✅ The Workflow is **Active** in the dashboard.
* ✅ You can see live video in the Cyberwave Digital Twin interface.
### Test Case A: The "Safe" Worker