OTA Updates

TwinEdge OTA (Over-The-Air) updates allow you to remotely update edge device firmware and software without physical access.

Professional Feature

OTA Updates are available on Professional and Enterprise plans.

Overview

What Can Be Updated

Component	Update Method
TwinEdge Edge firmware	Full package
Protocol adapters	Container image
ML models	Model file
Configuration	Config push
System packages	Package manager

Update Flow

Package Upload → Validation → Deployment Created →
Rollout Strategy → Device Download → Install → Verify → Report

Package Management

Uploading Packages

1. Go to Fleet → OTA → Packages
2. Click Upload Package
3. Fill in details:
   • Name: Package identifier
   • Version: Semantic version (e.g., 2.1.0)
   • Device Type: Target hardware
   • Release Notes: What's changed
4. Upload the package file
5. Click Upload

Package Validation

TwinEdge validates packages:

• Checksum: SHA-256 integrity check
• Size limits: Max 500MB per package
• Format: Supported archive types
• Signature: Optional cryptographic signing

Package States

State	Description
Draft	Uploaded, not released
Released	Available for deployment
Deprecated	No longer recommended
Archived	Hidden from lists

Releasing Packages

1. Open the package details
2. Review checksums and metadata
3. Click Release
4. Package becomes available for deployment

Creating Deployments

New Deployment

1. Go to Fleet → OTA → Deployments
2. Click New Deployment
3. Complete the wizard:

Step 1: Select Package

• Choose the package and version
• Review release notes

Step 2: Select Targets

• All Devices: Every compatible device
• Device Groups: Specific groups
• Individual Devices: Hand-picked devices

Step 3: Configure Rollout

• Choose rollout strategy
• Set timing options

Step 4: Review & Deploy

• Confirm settings
• Name the deployment
• Click Start Deployment

Rollout Strategies

Immediate

Deploy to all targets at once.

strategy: immediate

Best for:

• Small deployments (fewer than 10 devices)
• Non-critical updates
• Test environments

Phased Rollout

Gradually deploy to increasing percentages:

strategy: phased
phases:
  - percent: 10
    wait_hours: 24
  - percent: 50
    wait_hours: 24
  - percent: 100

Best for:

• Large fleets
• Critical updates
• Production environments

Canary

Deploy to a small test group first:

strategy: canary
canary_percent: 5
canary_duration_hours: 48

Best for:

• Major version updates
• High-risk changes
• Validating in production

Scheduling

Deploy Now: Start immediately after creation.

Schedule: Set a future date/time:

Start: 2026-01-10 02:00 AM EST

Maintenance Window: Only deploy during defined windows:

Allowed: Sat-Sun 00:00-06:00

Monitoring Deployments

Deployment Dashboard

View deployment status:

• Progress bar: Overall completion
• Phase indicator: Current rollout phase
• Device counts: Success/Failed/Pending

Per-Device Status

Status	Meaning
Pending	Waiting to start
Downloading	Fetching package
Installing	Applying update
Verifying	Running health checks
Completed	Successfully updated
Failed	Update failed
Rolled Back	Reverted to previous

Device Logs

Click a device to see detailed logs:

[10:00:01] Received update notification
[10:00:05] Downloading package v2.1.0 (52MB)
[10:02:30] Download complete, checksum verified
[10:02:35] Stopping services
[10:02:40] Applying update
[10:05:15] Restarting services
[10:05:30] Running health check
[10:05:35] Health check passed
[10:05:36] Update complete

Rollback

Automatic Rollback

Enable automatic rollback for failed updates:

rollback:
  enabled: true
  trigger: health_check_failed
  keep_previous_versions: 2

When triggered:

1. Failed device reverts to previous version
2. Admin notified of rollback
3. Device marked as "Rolled Back"

Manual Rollback

Rollback a deployment:

1. Open deployment details
2. Click Rollback
3. Select devices to roll back
4. Confirm action

Rollback Candidates

View devices eligible for rollback:

1. Go to Fleet → OTA → Rollbacks
2. See recent updates with rollback available
3. Select and initiate rollback

Health Checks

Post-Update Verification

After installation, TwinEdge runs health checks:

health_checks:
  - type: service_running
    services: [opcua-server, ml-inference, dashboard]

  - type: api_responsive
    endpoint: /health
    timeout_seconds: 30

  - type: custom_script
    script: /opt/twinedge/healthcheck.sh

Health Check Results

Result	Action
Pass	Mark as completed
Fail	Trigger rollback (if enabled)
Timeout	Retry, then fail

Update Agents

TwinEdge Update Agent

Pre-installed on TwinEdge Edge devices:

• Listens for update notifications via MQTT
• Downloads packages securely
• Applies updates with minimal downtime
• Reports progress to cloud

Agent Configuration

# /etc/twinedge/ota.yaml
ota:
  enabled: true
  check_interval_seconds: 300
  download_path: /var/twinedge/ota
  verify_signature: true
  auto_reboot: true
  backup_before_update: true

Security

Package Signing

Sign packages for integrity:

1. Generate signing keys (RSA 4096-bit)
2. Configure public key on devices
3. Sign packages before upload

# Sign a package
twinedge-ota sign package.tar.gz --key private.pem

# Verify signature
twinedge-ota verify package.tar.gz --key public.pem

Secure Transport

All OTA traffic uses:

• HTTPS for package downloads
• TLS 1.3 for MQTT notifications
• Certificate pinning (optional)

Access Control

Permissions for OTA operations:

Action	Required Role
View deployments	Viewer
Create deployment	Operator
Approve deployment	Admin
Rollback	Admin

Best Practices

Testing Updates

1. Test on development devices first
2. Use canary deployments for production
3. Validate health checks are comprehensive
4. Have rollback plan ready

Timing Updates

• Schedule during low-activity periods
• Avoid critical production times
• Consider time zones for global fleets
• Use maintenance windows

Communication

• Notify operators before updates
• Document what's changing
• Provide rollback instructions
• Have support available during rollout

Monitoring

• Watch deployment progress actively
• Monitor device health post-update
• Check for increased error rates
• Validate functionality after completion

Troubleshooting

Update Stuck at Downloading

1. Check device internet connectivity
2. Verify package URL is accessible
3. Check available disk space
4. Review firewall rules

Health Check Failing

1. SSH to device and check service status
2. Review service logs
3. Manually run health check script
4. Check for resource exhaustion

Rollback Not Working

1. Verify previous version is retained
2. Check disk space for rollback
3. Review rollback logs
4. Manual intervention may be required

API Reference

List Packages

GET /api/v1/ota/packages
Authorization: Bearer YOUR_API_KEY

Create Deployment

POST /api/v1/ota/deployments
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "name": "Production Update v2.1.0",
  "package_id": "pkg-123",
  "targets": {
    "type": "group",
    "group_id": "production-devices"
  },
  "strategy": "phased",
  "phases": [
    {"percent": 10, "wait_hours": 24},
    {"percent": 50, "wait_hours": 24},
    {"percent": 100}
  ]
}

Get Deployment Status

GET /api/v1/ota/deployments/{id}
Authorization: Bearer YOUR_API_KEY

Initiate Rollback

POST /api/v1/ota/deployments/{id}/rollback
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "device_ids": ["device-1", "device-2"]
}

Next Steps

• Fleet Overview - Manage your device fleet
• Protocols - Update protocol configurations
• Troubleshooting - Resolve update issues