Zelta/Documentation
GitHub

AWS IoT Core Integration

Integrate Zelta with AWS IoT Core to route device messages to your AWS infrastructure while maintaining Zelta's OTA capabilities.

Overview

The AWS IoT Core integration allows you to:

  • ✅ Route device heartbeats, telemetry, and events to AWS
  • ✅ Keep Zelta for firmware updates and device management
  • ✅ Use AWS services (Lambda, Kinesis, S3, etc.) for data processing
  • ✅ Maintain a single MQTT connection from devices to Zelta

Architecture

Device → Zelta MQTT Broker → Zelta Cloud (OTA)
              ↓
         AWS IoT Core → Your AWS Services

Prerequisites

  1. AWS Account with IoT Core enabled
  2. Zelta Account (Pro plan or higher for cloud integrations)
  3. AWS IoT Thing created for the bridge connection

Setup Steps

1. Create AWS IoT Thing

# Create a thing in AWS IoT Core
aws iot create-thing --thing-name zelta-bridge-org-123

# Create and attach certificate
aws iot create-keys-and-certificate \
  --set-as-active \
  --certificate-pem-outfile zelta-bridge.crt \
  --public-key-outfile zelta-bridge.public.key \
  --private-key-outfile zelta-bridge.private.key

# Note the certificate ARN from the output

2. Create IoT Policy

Create a policy that allows publishing to device topics:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["iot:Connect"],
      "Resource": "arn:aws:iot:REGION:ACCOUNT_ID:client/zelta-bridge-*"
    },
    {
      "Effect": "Allow",
      "Action": ["iot:Publish"],
      "Resource": "arn:aws:iot:REGION:ACCOUNT_ID:topic/devices/*"
    },
    {
      "Effect": "Allow",
      "Action": ["iot:Subscribe", "iot:Receive"],
      "Resource": "*"
    }
  ]
}

# Create policy
aws iot create-policy \
  --policy-name ZeltaBridgePolicy \
  --policy-document file://policy.json

# Attach policy to certificate
aws iot attach-policy \
  --policy-name ZeltaBridgePolicy \
  --target CERTIFICATE_ARN

3. Download Amazon Root CA

curl -o AmazonRootCA1.pem \
  https://www.amazontrust.com/repository/AmazonRootCA1.pem

4. Configure in Zelta Dashboard

  1. Go to Settings → Cloud Integrations

  2. Click Add Integration → AWS IoT Core

  3. Fill in the form:

    • Name: My AWS IoT Integration
    • AWS Endpoint: xxxxx.iot.us-east-1.amazonaws.com (from AWS console)
    • AWS Region: us-east-1
    • Device Certificate: Paste contents of zelta-bridge.crt
    • Private Key: Paste contents of zelta-bridge.private.key
    • CA Certificate: Paste contents of AmazonRootCA1.pem

  4. Configure message routing:

    • ✅ Forward Heartbeats
    • ✅ Forward Telemetry
    • ⬜ Forward Events
    • ⬜ Forward Logs

  5. Set up topic mapping (optional):

{
  "zelta/+/+/up/heartbeat": "devices/{device_id}/heartbeat",
  "zelta/+/+/up/telemetry": "devices/{device_id}/telemetry",
  "zelta/+/+/up/event": "devices/{device_id}/events"
}
  1. Click Test Connection to verify
  2. Click Save and Activate

Topic Mapping

Default Mapping

If no custom mapping is provided, Zelta uses:

| Zelta Topic | AWS Topic | |------------|-----------| | zelta/{product}/{device}/up/heartbeat | devices/{device_id}/heartbeat | | zelta/{product}/{device}/up/telemetry | devices/{device_id}/telemetry | | zelta/{product}/{device}/up/event | devices/{device_id}/event | | zelta/{product}/{device}/up/log | devices/{device_id}/log |

Custom Mapping

You can customize topic mapping with placeholders:

  • {device_id} - Device ID
  • {product_id} - Product ID
  • {org_id} - Organization ID

Example:

{
  "zelta/+/+/up/#": "zelta/{org_id}/{device_id}/upstream",
  "zelta/+/+/up/heartbeat": "telemetry/heartbeat/{device_id}"
}

Use Cases

1. Device Shadow Sync

Route device heartbeats to update AWS IoT Device Shadows:

// AWS IoT Rule
SELECT * FROM 'devices/+/heartbeat'

// Lambda function to update shadow
exports.handler = async (event) => {
  const deviceId = event.topic.split('/')[1];
  await iotData.updateThingShadow({
    thingName: deviceId,
    payload: JSON.stringify({
      state: {
        reported: {
          online: true,
          lastSeen: Date.now(),
          firmwareVersion: event.version
        }
      }
    })
  }).promise();
};

2. Analytics Pipeline

Stream telemetry to AWS services:

AWS IoT Core → Kinesis Data Streams → Lambda → S3/DynamoDB
                                    → QuickSight for dashboards

3. Alerting

Trigger alerts based on device events:

AWS IoT Rule → SNS Topic → Email/SMS/Lambda

Security Best Practices

  1. Least Privilege: Grant only necessary IoT permissions
  2. Rotate Certificates: Regenerate certificates every 90 days
  3. Monitor Usage: Use CloudWatch to track published messages
  4. Separate Things: Use different AWS Things per environment (dev/prod)
  5. Encrypt at Rest: Enable AWS encryption for IoT data

Troubleshooting

Connection Failed

Check:

  1. Endpoint URL is correct (no https:// prefix)
  2. Certificate and private key match
  3. Certificate is attached to policy
  4. AWS IoT policy allows iot:Connect and iot:Publish

Messages Not Appearing

  1. Check Zelta dashboard for integration status
  2. Verify topic mapping is correct
  3. Test with AWS IoT Core MQTT Test Client
  4. Check CloudWatch Logs for errors

High Latency

  1. Choose AWS region closest to your Zelta server
  2. Enable AWS IoT Analytics for buffering
  3. Use batch publishing if sending many messages

Pricing

  • Zelta: Cloud integrations available on Pro plan ($29/mo) and higher
  • AWS IoT Core:
    • $1.00 per million messages (first 1B)
    • $0.08 per million device shadows updates

Next Steps