Roboticks SDK Integration Plan

Executive Summary

This document outlines the integration plan for incorporating all new Roboticks platform features into the roboticks-sdk. The goal is to evolve the SDK from a simple “Hello World” demo into a production-ready system that leverages the full capabilities of the platform.

1. Current State Analysis

SDK Capabilities (What We Have)

✅ Device registration and credential provisioning
✅ Session lifecycle management
✅ Real-time log streaming via MQTT
✅ Heartbeat monitoring
✅ Command polling (HTTP + MQTT)
✅ File upload via S3 presigned URLs
✅ ZeroMQ local messaging
✅ Module framework with auto-registration

Platform Features (What We Need to Integrate)

🆕 Compositions - Docker multi-container deployments from ECR
🆕 Capsules - Native binary/edge ML model packages
🆕 Configurations - Environment variable management
🆕 Packages (Deployments) - Versioned releases combining capsules + compositions + configs
🆕 Rollouts - Progressive deployment strategies (canary, blue/green, offline)
🆕 Environments - Fleet-wide and device-specific variable overrides
🆕 Commands - Enhanced command system with timeout/retry
🆕 Reverse Tunnels - Secure SSH/HTTP access to edge devices
🆕 Device Groups - Logical device organization for targeted deployments

2. Integration Architecture

2.1 High-Level Component Design

┌─────────────────────────────────────────────────────────────┐
│                    Roboticks Platform (Cloud)                │
├─────────────────────────────────────────────────────────────┤
│  - Deployments API (packages)                                │
│  - Rollouts API (progressive deployment strategies)          │
│  - Environment Configs API (variable management)             │
│  - Reverse Tunnel API (secure device access)                 │
│  - Compositions API (ECR integration)                        │
│  - Device Groups API (fleet organization)                    │
└─────────────────────────────────────────────────────────────┘
                           ↕ MQTT + HTTPS
┌─────────────────────────────────────────────────────────────┐
│              Roboticks SDK - Device Manager (Enhanced)       │
├─────────────────────────────────────────────────────────────┤
│  NEW COMPONENTS:                                             │
│  ┌──────────────────────────────────────────────────────┐  │
│  │ 1. Deployment Manager                                 │  │
│  │    - Download packages (capsules + compositions)      │  │
│  │    - Verify signatures and checksums                  │  │
│  │    - Install capsules (native binaries)               │  │
│  │    - Pull and run Docker compositions                 │  │
│  └──────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │ 2. Environment Manager                                │  │
│  │    - Fetch environment configs from cloud             │  │
│  │    - Apply device-specific overrides                  │  │
│  │    - Inject variables into modules/containers         │  │
│  │    - Watch for real-time updates (no rebuild)         │  │
│  └──────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │ 3. Rollout Controller                                 │  │
│  │    - Receive rollout instructions from cloud          │  │
│  │    - Execute deployment with strategy (canary, etc.)  │  │
│  │    - Report progress (downloading, installing, etc.)  │  │
│  │    - Health check validation                          │  │
│  │    - Automatic rollback on failure                    │  │
│  └──────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │ 4. Reverse Tunnel Agent                               │  │
│  │    - Establish SSH reverse tunnel to cloud proxy      │  │
│  │    - Support HTTP/HTTPS tunneling                     │  │
│  │    - Authentication via device certificate            │  │
│  │    - Auto-reconnect with exponential backoff          │  │
│  └──────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │ 5. Update Orchestrator                                │  │
│  │    - Coordinate updates across native + Docker        │  │
│  │    - Graceful shutdown of existing modules            │  │
│  │    - Zero-downtime updates (blue/green)               │  │
│  │    - Version tracking and history                     │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                              │
│  EXISTING COMPONENTS (Enhanced):                             │
│  - Session Manager - now tracks deployment versions         │
│  - Log Collector - adds deployment context to logs          │
│  - Command Executor - enhanced with new command types       │
│  - Heartbeat - reports current deployment status            │
└─────────────────────────────────────────────────────────────┘
                           ↕ ZeroMQ / Iceoryx
┌─────────────────────────────────────────────────────────────┐
│              Application Layer                               │
├─────────────────────────────────────────────────────────────┤
│  - Native Modules (Capsules) - C++ robotics modules         │
│  - Docker Compositions - containerized services             │
│  - Edge ML Models - TensorFlow Lite, ONNX Runtime           │
└─────────────────────────────────────────────────────────────┘

3. Feature Integration Breakdown

3.1 Capsules (Native Binary Packages)

What Are Capsules?

Versioned native binaries compiled for target architecture (ARM64, x86_64)
Include: executables, shared libraries, configuration files, ML models
Current SDK modules (HelloWorldModule) will be packaged as capsules

Integration Plan:

Backend Changes

Add capsule metadata to device session tracking
Store capsule version in fleet_devices.active_capsule_id
Track installation history in new table: capsule_installations

SDK Changes

New File: /packages/roboticks-device/include/CapsuleManager.hpp

class CapsuleManager {
public:
    // Download capsule from S3 via presigned URL
    bool DownloadCapsule(const std::string& capsule_id,
                         const std::string& version);

    // Verify checksum (SHA256) and signature (optional)
    bool VerifyCapsule(const std::string& capsule_path);

    // Extract to /opt/roboticks/capsules/{capsule_name}/{version}/
    bool InstallCapsule(const std::string& capsule_path);

    // Launch capsule process with environment variables
    bool LaunchCapsule(const std::string& capsule_name,
                       const std::map<std::string, std::string>& env_vars);

    // Gracefully stop running capsule
    bool StopCapsule(const std::string& capsule_name);

    // List installed capsules
    std::vector<CapsuleInfo> ListInstalledCapsules();
};

Directory Structure:

/opt/roboticks/
├── capsules/
│   ├── hello-world-module/
│   │   ├── v1.0.0/
│   │   │   ├── bin/HelloWorldModule
│   │   │   ├── lib/librobotics-messaging.so
│   │   │   └── config/module.yaml
│   │   └── v1.1.0/
│   └── perception-pipeline/
│       └── v2.3.0/
├── compositions/
│   └── (Docker Compose manifests)
└── config/
    ├── device.yaml
    └── environment.yaml

API Endpoints Used:

GET /api/v1/organizations/{org}/projects/{project}/deployments/{deployment_id}/download - Get presigned S3 URL
POST /api/v1/organizations/{org}/projects/{project}/deployments/{deployment_id}/status - Report installation progress

MQTT Topics:

Publish: roboticks/devices/{dsn}/capsule-status - Installation progress
Subscribe: roboticks/devices/{dsn}/capsule-install - Install command

3.2 Compositions (Docker Multi-Container)

What Are Compositions?

Docker Compose-style multi-container applications
Stored in AWS ECR (Elastic Container Registry)
Examples: ROS2 nodes, ML inference servers, web UIs, databases

Integration Plan:

SDK Changes

New File: /packages/roboticks-device/include/CompositionManager.hpp

class CompositionManager {
public:
    // Authenticate with ECR using IAM role
    bool AuthenticateECR(const std::string& ecr_endpoint);

    // Pull Docker image from ECR
    bool PullImage(const std::string& image_uri);

    // Parse Docker Compose YAML and launch containers
    bool DeployComposition(const std::string& compose_yaml,
                           const std::map<std::string, std::string>& env_vars);

    // Stop and remove containers
    bool StopComposition(const std::string& composition_name);

    // Get container status and logs
    std::vector<ContainerStatus> GetContainerStatus();

    // Health check for running containers
    bool HealthCheck(const std::string& composition_name);
};

Docker Integration:

Requires Docker Engine or Docker Compose CLI on edge device
SDK calls Docker API via Unix socket (/var/run/docker.sock)
Composition manifests downloaded from backend as YAML files

API Endpoints:

GET /api/v1/organizations/{org}/projects/{project}/compositions - List available compositions
GET /api/v1/organizations/{org}/projects/{project}/compositions/{tag} - Get specific composition manifest

Environment Variable Injection:

# Example composition with variables
version: '3.8'
services:
  perception:
    image: 123456789.dkr.ecr.us-east-1.amazonaws.com/robotics-perception:v2.1.0
    environment:
      - CAMERA_FPS=${CAMERA_FPS}  # From environment config
      - MODEL_PATH=${MODEL_PATH}
      - LOG_LEVEL=${LOG_LEVEL}
    volumes:
      - /opt/roboticks/models:/models:ro

3.3 Configurations (Environment Variables)

What Are Configurations?

Named sets of environment variables (e.g., “production”, “staging”, “debug”)
Two scopes: Fleet-wide (PROJECT) and Device-specific (DEVICE)
Changes propagate instantly without rebuilding images

Integration Plan:

SDK Changes

New File: /packages/roboticks-device/include/EnvironmentManager.hpp

class EnvironmentManager {
public:
    // Fetch environment config from cloud
    bool FetchConfiguration(const std::string& config_name);

    // Merge fleet-wide + device-specific variables
    std::map<std::string, std::string> GetMergedEnvironment();

    // Watch for real-time updates via MQTT
    void StartWatchingUpdates();

    // Apply updated variables to running modules/containers
    bool ApplyUpdates(const std::map<std::string, std::string>& updated_vars);

    // Cache locally for offline operation
    bool CacheConfiguration();
};

Variable Precedence:

Device-specific variables (highest priority)
Fleet-wide (PROJECT) variables
Default values from capsule/composition config
System environment variables (lowest priority)

API Endpoints:

GET /api/v1/organizations/{org}/projects/{project}/environment-configs - List configs
GET /api/v1/organizations/{org}/projects/{project}/environment-variables?device_id={dsn} - Get merged variables
Subscribe: roboticks/devices/{dsn}/environment-update - Real-time updates

Use Cases:

Change camera resolution without redeploying
Toggle debug logging on specific devices
Update ML model paths dynamically
Configure API endpoints per environment

3.4 Packages (Deployments)

What Are Packages?

Versioned releases that bundle:
- Capsules (optional)
- Compositions (optional)
- Configurations (optional)
A complete deployable unit (e.g., “Perception Pipeline v2.3.0”)

Integration Plan:

SDK Changes

New File: /packages/roboticks-device/include/DeploymentManager.hpp

class DeploymentManager {
public:
    struct Deployment {
        std::string deployment_id;
        std::string name;
        std::string version;
        std::vector<std::string> capsule_ids;
        std::vector<std::string> composition_tags;
        std::string configuration_id;
    };

    // Fetch deployment metadata
    bool FetchDeployment(const std::string& deployment_id);

    // Download all components (capsules + compositions + config)
    bool DownloadComponents();

    // Install in correct order
    bool InstallDeployment();

    // Start all components
    bool StartDeployment();

    // Stop and clean up
    bool StopDeployment();

    // Get current active deployment
    std::optional<Deployment> GetActiveDeployment();
};

Installation Flow:

1. Fetch deployment metadata from cloud
   ↓
2. Download capsules to /tmp/roboticks/downloads/
   ↓
3. Download Docker Compose manifests
   ↓
4. Fetch environment configuration
   ↓
5. Verify checksums and signatures
   ↓
6. Stop existing deployment (graceful shutdown)
   ↓
7. Install capsules to /opt/roboticks/capsules/{name}/{version}/
   ↓
8. Pull Docker images from ECR
   ↓
9. Inject environment variables
   ↓
10. Launch capsules + Docker containers
    ↓
11. Health check validation
    ↓
12. Report success/failure to cloud

API Endpoints:

GET /api/v1/organizations/{org}/projects/{project}/deployments/{deployment_id} - Get full deployment details
POST /api/v1/organizations/{org}/projects/{project}/deployments/{deployment_id}/status - Report status

3.5 Rollouts (Progressive Deployments)

What Are Rollouts?

Controlled deployment strategies for fleet updates
Strategies: All at Once, Progressive (10% → 50% → 100%), Canary (5%), Blue/Green, Offline

Integration Plan:

SDK Changes

New File: /packages/roboticks-device/include/RolloutController.hpp

class RolloutController {
public:
    struct RolloutInstruction {
        std::string rollout_id;
        std::string deployment_id;
        RolloutStrategy strategy;
        int stage_number;
        std::chrono::seconds wait_before_install;
        bool health_check_enabled;
        bool auto_rollback_enabled;
    };

    // Poll for assigned rollouts
    std::optional<RolloutInstruction> PollRollout();

    // Execute rollout based on strategy
    bool ExecuteRollout(const RolloutInstruction& instruction);

    // Report progress to cloud
    bool ReportProgress(const std::string& rollout_id,
                        RolloutStatus status,
                        int progress_percentage,
                        const std::string& error_message = "");

    // Perform health check after installation
    bool HealthCheck();

    // Rollback to previous deployment
    bool Rollback();
};

enum class RolloutStatus {
    PENDING,
    DOWNLOADING,
    INSTALLING,
    VERIFYING,
    COMPLETED,
    FAILED
};

Rollout Execution Flow:

1. Device polls for assigned rollouts
   ↓
2. Receives rollout instruction with stage number
   ↓
3. Wait for stage delay (if progressive strategy)
   ↓
4. Report status: DOWNLOADING
   ↓
5. Download deployment components
   ↓
6. Report status: INSTALLING
   ↓
7. Install deployment
   ↓
8. Report status: VERIFYING
   ↓
9. Perform health check
   ↓
10. If health check passes: Report COMPLETED
    If health check fails: Rollback and report FAILED

API Endpoints:

GET /api/v1/organizations/{org}/projects/{project}/device-rollouts?device_id={dsn} - Get assigned rollout
POST /api/v1/organizations/{org}/projects/{project}/rollouts/{rollout_id}/device-status - Report progress

MQTT Topics:

Subscribe: roboticks/devices/{dsn}/rollout - Real-time rollout assignment
Publish: roboticks/devices/{dsn}/rollout-progress - Progress updates

Offline Rollout Strategy:

Device downloads offline bundle (ZIP file)
Bundle includes: capsules, Docker images (tar), manifests, checksums
Device extracts and installs from local storage
Useful for air-gapped environments or limited bandwidth

3.6 Commands (Enhanced)

Current State:

Basic command polling via HTTP
Simple execute/acknowledge flow

Enhancements Needed:

SDK Changes

Enhanced File: /packages/roboticks-device/include/CommandExecutor.hpp

class CommandExecutor {
public:
    struct Command {
        std::string command_id;
        CommandType type;
        nlohmann::json payload;
        std::chrono::seconds timeout;
        int max_retries;
        std::chrono::system_clock::time_point scheduled_at;
    };

    enum class CommandType {
        START_SESSION,
        STOP_SESSION,
        RESTART_MODULE,
        UPDATE_ENVIRONMENT,
        COLLECT_DIAGNOSTICS,
        REBOOT_DEVICE,
        INSTALL_DEPLOYMENT,  // NEW
        STOP_DEPLOYMENT,     // NEW
        START_TUNNEL,        // NEW
        STOP_TUNNEL          // NEW
    };

    // Poll for new commands
    std::vector<Command> PollCommands();

    // Execute command with timeout
    CommandResult ExecuteCommand(const Command& cmd);

    // Acknowledge execution
    bool AcknowledgeCommand(const std::string& command_id,
                           CommandStatus status,
                           const std::string& output);
};

New Command Types:

INSTALL_DEPLOYMENT - Trigger deployment installation
STOP_DEPLOYMENT - Stop running deployment
COLLECT_DIAGNOSTICS - Upload logs, system metrics, dmesg, etc.
START_TUNNEL - Create reverse tunnel
STOP_TUNNEL - Close reverse tunnel

3.7 Reverse Tunnels (Secure Remote Access)

What Are Reverse Tunnels?

SSH reverse tunnels from edge device to cloud proxy
Enables secure access to devices behind NAT/firewall
Use cases: SSH, HTTP/HTTPS, VNC, Jupyter notebooks

Integration Plan:

Backend Infrastructure

Deploy SSH jump server (AWS EC2 or Fargate)
Generate unique subdomain per tunnel: {tunnel_id}.tunnels.roboticks.io
Use AWS Application Load Balancer for HTTPS termination
Store tunnel metadata in database

SDK Changes

New File: /packages/roboticks-device/include/ReverseTunnelAgent.hpp

class ReverseTunnelAgent {
public:
    struct TunnelConfig {
        std::string tunnel_id;
        std::string jump_server_host;  // tunnel-proxy.roboticks.io
        int jump_server_port;          // 22 (SSH)
        int local_port;                // 8080 (device-side service)
        int remote_port;               // 30000-39999 (cloud-side proxy)
        TunnelProtocol protocol;       // SSH, HTTP, HTTPS
        bool require_auth;
    };

    // Establish reverse SSH tunnel using device certificate
    bool CreateTunnel(const TunnelConfig& config);

    // Close tunnel
    bool CloseTunnel(const std::string& tunnel_id);

    // Monitor tunnel health and auto-reconnect
    void MonitorTunnel();

    // List active tunnels
    std::vector<TunnelInfo> ListActiveTunnels();
};

SSH Command:

# Device executes:
ssh -i /etc/roboticks/id_rsa \
    -N -R 0.0.0.0:30123:localhost:8080 \
    -o StrictHostKeyChecking=no \
    -o ServerAliveInterval=30 \
    tunnel-user@tunnel-proxy.roboticks.io

Authentication:

Device uses same X.509 certificate for SSH (convert to SSH format)
Jump server validates device certificate against database
ACL: Only authorized users can access tunnels

API Endpoints:

GET /api/v1/reverse-tunnels/devices/{dsn}/reverse-tunnels - List device tunnels
POST /api/v1/reverse-tunnels/devices/{dsn}/reverse-tunnels - Create tunnel
DELETE /api/v1/reverse-tunnels/{tunnel_id} - Close tunnel

Frontend:

Show tunnel status in device overview
Copy public URL to clipboard
One-click SSH/HTTP access

3.8 Device Groups (Fleet Organization)

What Are Device Groups?

Logical collections of devices (e.g., “Production Fleet”, “Beta Testers”)
Target deployments to groups instead of individual devices
Dynamic membership based on tags or manual assignment

Integration Plan:

SDK Changes

No major SDK changes required
Device reports tags in heartbeat
Backend assigns device to groups based on tags
Rollouts target device groups

Device Tagging:

# HelloWorldDevice.yaml
device:
  name: "hello-world-device-001"
  type: "OTHER"
  tags:
    - "production"
    - "region:us-west"
    - "version:v1.0.0"

API Endpoints:

GET /api/v1/organizations/{org}/projects/{project}/device-groups - List groups
POST /api/v1/organizations/{org}/projects/{project}/device-groups/{group_id}/devices - Add device to group

4. Implementation Phases

Phase 1: Core Deployment Infrastructure (2-3 weeks)

Priority: HIGH Backend:

✅ Already complete: Deployments, Capsules, Configurations APIs

SDK:

Implement DeploymentManager (download, install, launch)
Implement CapsuleManager (native binary handling)
Implement EnvironmentManager (config fetching and merging)
Add deployment tracking to heartbeat

Testing:

Deploy HelloWorldModule as capsule
Apply environment config to running module
Verify version tracking in dashboard

Phase 2: Docker Composition Support (2 weeks)

Priority: HIGH SDK:

Implement CompositionManager (Docker integration)
ECR authentication via IAM role
Docker Compose parsing and execution
Container health monitoring

Testing:

Create Docker Compose with ROS2 nodes
Deploy to device via platform
Verify container logs in dashboard

Phase 3: Progressive Rollouts (2 weeks)

Priority: MEDIUM Backend:

✅ Already complete: Rollouts API

SDK:

Implement RolloutController
Progressive deployment strategies
Health check validation
Automatic rollback on failure

Testing:

Create rollout with canary strategy (5% → 100%)
Verify staged deployment
Test auto-rollback on failed health check

Phase 4: Reverse Tunnels (1-2 weeks)

Priority: MEDIUM Backend:

Deploy SSH jump server (EC2 or Fargate)
Configure ALB for HTTPS tunneling
Implement tunnel authentication

SDK:

Implement ReverseTunnelAgent
SSH tunnel establishment
Auto-reconnect logic
Tunnel health monitoring

Testing:

Create tunnel to device HTTP service
Access via public URL
Verify authentication and ACL

Phase 5: Offline Deployments (1 week)

Priority: LOW Backend:

Generate offline bundle (ZIP with checksums)
Include Docker images as tar files

SDK:

Offline bundle extraction
Docker image loading from tar
Manifest-based installation

Testing:

Download offline bundle
Deploy on air-gapped device
Verify installation without internet

Phase 6: Enhanced Commands (1 week)

Priority: LOW SDK:

Add new command types (diagnostics, deployment control)
Timeout and retry logic
Command scheduling

Testing:

Send COLLECT_DIAGNOSTICS command
Verify diagnostic bundle upload

5. Updated HelloWorld Demo

Before (Current State)

HelloWorldComposition/
├── HelloWorldComposition.yaml  # Module list
├── HelloWorldDevice.yaml       # Device config
└── run.sh                      # Launcher script

After (Enhanced)

HelloWorldComposition/
├── composition.yaml            # Docker Compose manifest
├── capsule.yaml                # Capsule metadata
├── environment.yaml            # Environment config
└── deployment.yaml             # Combined deployment manifest

# Docker Compose (composition.yaml)
services:
  hello-world-module:
    image: robotics/hello-world:v1.0.0
    environment:
      - MESSAGE_INTERVAL=${MESSAGE_INTERVAL}
      - LOG_LEVEL=${LOG_LEVEL}

  hello-subscriber:
    image: robotics/hello-subscriber:v1.0.0
    depends_on:
      - hello-world-module

# Environment Config (environment.yaml)
variables:
  MESSAGE_INTERVAL: "1.0"
  LOG_LEVEL: "INFO"
  MQTT_ENDPOINT: "a1b2c3d4-ats.iot.us-east-1.amazonaws.com"

# Deployment Manifest (deployment.yaml)
name: "Hello World Complete Example"
version: "v1.0.0"
components:
  capsule: "hello-world-module"
  composition: "hello-world:v1.0.0"
  configuration: "production"
rollout_strategy: "all_at_once"

Demo Flow (End-to-End)

Developer builds HelloWorld module (C++)
Upload capsule to S3 via CLI: roboticks capsule upload hello-world-module.tar.gz
Build Docker image and push to ECR: docker push 123456789.dkr.ecr.us-east-1.amazonaws.com/hello-world:v1.0.0
Create environment config via dashboard
Create deployment package bundling capsule + composition + config
Create rollout targeting device group
Device receives rollout assignment
Device downloads and installs deployment
Device reports success
Dashboard shows deployment status

6. API Changes Summary

New SDK → Backend Communication

Deployment APIs:

GET /api/v1/organizations/{org}/projects/{project}/deployments/{deployment_id} - Fetch deployment details
POST /api/v1/organizations/{org}/projects/{project}/deployments/{deployment_id}/status - Report installation status

Rollout APIs:

GET /api/v1/organizations/{org}/projects/{project}/device-rollouts?device_id={dsn} - Get assigned rollout
POST /api/v1/organizations/{org}/projects/{project}/rollouts/{rollout_id}/device-status - Report progress

Environment APIs:

GET /api/v1/organizations/{org}/projects/{project}/environment-variables?device_id={dsn} - Get merged variables
GET /api/v1/organizations/{org}/projects/{project}/environment-configs/{config_id} - Get specific config

Composition APIs:

GET /api/v1/organizations/{org}/projects/{project}/compositions - List ECR images
GET /api/v1/organizations/{org}/projects/{project}/compositions/{tag}/manifest - Get Docker Compose YAML

Tunnel APIs:

GET /api/v1/reverse-tunnels/devices/{dsn}/reverse-tunnels - List device tunnels
POST /api/v1/reverse-tunnels/devices/{dsn}/reverse-tunnels - Create tunnel
DELETE /api/v1/reverse-tunnels/{tunnel_id} - Close tunnel

New MQTT Topics

Device → Cloud:

roboticks/devices/{dsn}/deployment-status - Installation progress
roboticks/devices/{dsn}/rollout-progress - Rollout stage updates
roboticks/devices/{dsn}/health-check - Post-deployment health
roboticks/devices/{dsn}/tunnel-status - Tunnel lifecycle events

Cloud → Device:

roboticks/devices/{dsn}/deployment-install - Install deployment
roboticks/devices/{dsn}/rollout - Rollout assignment
roboticks/devices/{dsn}/environment-update - Config changes
roboticks/devices/{dsn}/tunnel-create - Create tunnel

7. Security Considerations

Deployment Verification

Checksums: SHA256 hash verification for all downloads
Signatures: GPG signatures for capsules (optional)
TLS: All downloads via HTTPS (S3 presigned URLs)

ECR Authentication

IAM role-based authentication (no hardcoded credentials)
Temporary credentials via AWS STS
Scoped permissions: read-only access to specific ECR repositories

Reverse Tunnel Security

mTLS authentication using device certificate
ACL enforcement on jump server
Rate limiting to prevent abuse
Audit logging of all tunnel access

Environment Variable Security

Mark sensitive variables as “SECRET” type
Encrypt secrets at rest in database
Never log secret values
Use AWS Secrets Manager for production secrets

8. Monitoring and Observability

Metrics to Track

Deployment success/failure rate
Average deployment time
Rollout stage progression
Health check pass/fail rate
Tunnel connection uptime
Network bandwidth usage (downloads)
Disk space usage (/opt/roboticks/)

Logging Enhancements

Add deployment context to all logs (deployment_id, version)
Structured logging for deployment events
Upload installation logs to S3 for debugging
Real-time log streaming during deployments

Dashboard Widgets

Deployment status per device
Rollout progress visualization
Active tunnel list
Environment variable diff viewer
Deployment history timeline

9. Developer Experience Improvements

CLI Tool: `roboticks-cli`

# Device management
roboticks devices list
roboticks devices register --project-secret proj_xxx

# Deployment management
roboticks deployments list
roboticks deployments create --name "My Deployment" --version v1.0.0
roboticks deployments deploy --device-id DSN123 --deployment-id deploy_xxx

# Rollout management
roboticks rollouts create --deployment deploy_xxx --strategy canary
roboticks rollouts status --rollout-id rollout_xxx

# Environment management
roboticks env list
roboticks env set --key LOG_LEVEL --value DEBUG --device DSN123

# Tunnel management
roboticks tunnels create --device DSN123 --local-port 8080
roboticks tunnels list --device DSN123

VSCode Extension

Syntax highlighting for YAML manifests
IntelliSense for environment variables
One-click deployment to test devices
Real-time log streaming in IDE

Testing Tools

Local simulator for testing deployments
Mock cloud API server
Deployment verification script

10. Migration Path (Existing Users)

Backward Compatibility

Keep existing module launcher (run.sh) working
Support both old and new deployment formats
Graceful deprecation warnings

Migration Steps

Convert existing compositions to new format
Create capsule metadata for native modules
Extract environment configs from YAML files
Create initial deployment packages
Test deployments on dev devices
Roll out to production fleet

11. Success Metrics

Technical Metrics

✅ 99% deployment success rate
✅ < 5 minutes average deployment time
✅ Zero-downtime updates (blue/green)
✅ < 1% rollback rate
✅ Tunnel uptime > 99.9%

Business Metrics

✅ Reduce deployment time from hours to minutes
✅ Enable remote debugging via tunnels
✅ Support air-gapped deployments
✅ Simplify multi-container applications

12. Next Steps

Immediate Actions (Week 1)

Review this document with team
Finalize API contracts between backend and SDK
Set up development environment for SDK changes
Create feature branches for each component

Sprint Planning

Sprint 1-2: Phase 1 (Core Deployment Infrastructure)
Sprint 3-4: Phase 2 (Docker Composition Support)
Sprint 5-6: Phase 3 (Progressive Rollouts)
Sprint 7: Phase 4 (Reverse Tunnels)
Sprint 8: Phase 5-6 (Offline + Enhanced Commands)

Risk Mitigation

Risk: Docker not available on all devices
- Mitigation: Capsule-only deployments, detect Docker availability
Risk: Network bandwidth limitations
- Mitigation: Delta updates, compression, offline bundles
Risk: Device storage constraints
- Mitigation: Automatic cleanup of old versions, configurable retention policy

Appendix A: File Structure After Integration

roboticks-sdk/
├── packages/
│   ├── roboticks-device/
│   │   ├── include/
│   │   │   ├── DeviceManager.hpp
│   │   │   ├── DeploymentManager.hpp     # NEW
│   │   │   ├── CapsuleManager.hpp        # NEW
│   │   │   ├── CompositionManager.hpp    # NEW
│   │   │   ├── EnvironmentManager.hpp    # NEW
│   │   │   ├── RolloutController.hpp     # NEW
│   │   │   └── ReverseTunnelAgent.hpp    # NEW
│   │   └── src/
│   │       ├── DeviceManager.cpp
│   │       ├── DeploymentManager.cpp     # NEW
│   │       ├── CapsuleManager.cpp        # NEW
│   │       ├── CompositionManager.cpp    # NEW
│   │       ├── EnvironmentManager.cpp    # NEW
│   │       ├── RolloutController.cpp     # NEW
│   │       └── ReverseTunnelAgent.cpp    # NEW
│   ├── roboticks-messaging/
│   ├── roboticks-logging/
│   └── roboticks-module/
├── modules/
│   └── HelloWorldModule/
├── compositions/
│   └── HelloWorldComposition/
│       ├── composition.yaml              # Docker Compose
│       ├── capsule.yaml                  # Capsule metadata
│       ├── environment.yaml              # Environment config
│       └── deployment.yaml               # Deployment manifest
├── tools/
│   └── roboticks-cli/                    # NEW CLI tool
└── docs/
    ├── SDK_INTEGRATION_PLAN.md           # This document
    ├── DEPLOYMENT_GUIDE.md               # NEW
    └── TUNNEL_SETUP.md                   # NEW

Appendix B: Example Deployment Manifests

Full Deployment YAML

# deployment.yaml
apiVersion: v1
kind: Deployment
metadata:
  name: "Advanced Robotics Pipeline"
  version: "v2.5.0"
  description: "Full perception + navigation + control pipeline"

components:
  # Native C++ modules (capsules)
  capsules:
    - name: "perception-module"
      version: "v2.5.0"
      checksum: "sha256:abc123..."
      download_url: "https://s3.amazonaws.com/..."

    - name: "navigation-module"
      version: "v1.3.0"
      checksum: "sha256:def456..."
      download_url: "https://s3.amazonaws.com/..."

  # Docker containerized services (compositions)
  compositions:
    - name: "ml-inference-server"
      tag: "v1.2.0"
      image: "123456789.dkr.ecr.us-east-1.amazonaws.com/ml-inference:v1.2.0"

    - name: "web-dashboard"
      tag: "v3.0.0"
      image: "123456789.dkr.ecr.us-east-1.amazonaws.com/dashboard:v3.0.0"

  # Environment configuration
  configuration:
    name: "production"
    variables:
      LOG_LEVEL: "INFO"
      CAMERA_FPS: "30"
      MODEL_PATH: "/opt/roboticks/models/yolov8.onnx"
      MQTT_ENDPOINT: "a1b2c3d4-ats.iot.us-east-1.amazonaws.com"

# Rollout configuration
rollout:
  strategy: "progressive"
  stages:
    - percentage: 10
      wait_minutes: 30
    - percentage: 50
      wait_minutes: 60
    - percentage: 100
      wait_minutes: 0
  health_check:
    enabled: true
    endpoint: "http://localhost:8080/health"
    interval_seconds: 30
    timeout_seconds: 10
  auto_rollback:
    enabled: true
    on_health_check_failure: true

# Installation hooks
hooks:
  pre_install:
    - "systemctl stop legacy-service"
    - "mkdir -p /opt/roboticks/models"
  post_install:
    - "systemctl start roboticks-device-manager"
  pre_uninstall:
    - "backup-logs.sh"

Conclusion

This integration plan transforms the roboticks-sdk from a simple demo into a production-grade edge deployment platform. By integrating Compositions, Capsules, Configurations, Packages, Rollouts, Environments, Commands, and Reverse Tunnels, we enable:

Flexible Deployments: Mix native binaries and Docker containers
Progressive Rollouts: Minimize risk with canary and blue/green strategies
Dynamic Configuration: Update behavior without redeployment
Remote Access: Debug and inspect devices via secure tunnels
Offline Operation: Support air-gapped environments
Zero-Downtime Updates: Graceful shutdowns and health checks

The phased implementation approach ensures we can deliver value incrementally while maintaining backward compatibility.

Getting Started

Core Concepts

Features

SDK Documentation

​Roboticks SDK Integration Plan

​Executive Summary

​1. Current State Analysis

​SDK Capabilities (What We Have)

​Platform Features (What We Need to Integrate)

​2. Integration Architecture

​2.1 High-Level Component Design

​3. Feature Integration Breakdown

​3.1 Capsules (Native Binary Packages)

​Backend Changes

​SDK Changes

​3.2 Compositions (Docker Multi-Container)

​SDK Changes

​3.3 Configurations (Environment Variables)

​SDK Changes

​3.4 Packages (Deployments)

​SDK Changes

​3.5 Rollouts (Progressive Deployments)

​SDK Changes

​3.6 Commands (Enhanced)

​SDK Changes

​3.7 Reverse Tunnels (Secure Remote Access)

​Backend Infrastructure

​SDK Changes

​3.8 Device Groups (Fleet Organization)

​SDK Changes

​4. Implementation Phases

​Phase 1: Core Deployment Infrastructure (2-3 weeks)

​Phase 2: Docker Composition Support (2 weeks)

​Phase 3: Progressive Rollouts (2 weeks)

​Phase 4: Reverse Tunnels (1-2 weeks)

​Phase 5: Offline Deployments (1 week)

​Phase 6: Enhanced Commands (1 week)

​5. Updated HelloWorld Demo

​Before (Current State)

​After (Enhanced)

​Demo Flow (End-to-End)

​6. API Changes Summary

​New SDK → Backend Communication

​New MQTT Topics

​7. Security Considerations

​Deployment Verification

​ECR Authentication

​Reverse Tunnel Security

​Environment Variable Security

​8. Monitoring and Observability

​Metrics to Track

​Logging Enhancements

​Dashboard Widgets

​9. Developer Experience Improvements

​CLI Tool: roboticks-cli

​VSCode Extension

​Testing Tools

​10. Migration Path (Existing Users)

​Backward Compatibility

​Migration Steps

​11. Success Metrics

​Technical Metrics

​Business Metrics

​12. Next Steps

​Immediate Actions (Week 1)

​Sprint Planning

​Risk Mitigation

​Appendix A: File Structure After Integration

​Appendix B: Example Deployment Manifests

​Full Deployment YAML

​Conclusion

Roboticks SDK Integration Plan

Executive Summary

1. Current State Analysis

SDK Capabilities (What We Have)

Platform Features (What We Need to Integrate)

2. Integration Architecture

2.1 High-Level Component Design

3. Feature Integration Breakdown

3.1 Capsules (Native Binary Packages)

Backend Changes

SDK Changes

3.2 Compositions (Docker Multi-Container)

SDK Changes

3.3 Configurations (Environment Variables)

SDK Changes

3.4 Packages (Deployments)

SDK Changes

3.5 Rollouts (Progressive Deployments)

SDK Changes

3.6 Commands (Enhanced)

SDK Changes

3.7 Reverse Tunnels (Secure Remote Access)

Backend Infrastructure

SDK Changes

3.8 Device Groups (Fleet Organization)

SDK Changes

4. Implementation Phases

Phase 1: Core Deployment Infrastructure (2-3 weeks)

Phase 2: Docker Composition Support (2 weeks)

Phase 3: Progressive Rollouts (2 weeks)

Phase 4: Reverse Tunnels (1-2 weeks)

Phase 5: Offline Deployments (1 week)

Phase 6: Enhanced Commands (1 week)

5. Updated HelloWorld Demo

Before (Current State)

After (Enhanced)

Demo Flow (End-to-End)

6. API Changes Summary

New SDK → Backend Communication

New MQTT Topics

7. Security Considerations

Deployment Verification

ECR Authentication

Reverse Tunnel Security

Environment Variable Security

8. Monitoring and Observability

Metrics to Track

Logging Enhancements

Dashboard Widgets

9. Developer Experience Improvements

CLI Tool: `roboticks-cli`

VSCode Extension

Testing Tools

10. Migration Path (Existing Users)

Backward Compatibility

Migration Steps

11. Success Metrics

Technical Metrics

Business Metrics

12. Next Steps

Immediate Actions (Week 1)

Sprint Planning

Risk Mitigation

Appendix A: File Structure After Integration

Appendix B: Example Deployment Manifests

Full Deployment YAML

Conclusion