AIIOTLayer Integration Setup Guide

The AIIOTLayer integration provides IoT device management capabilities for AINexLayer agents using the ThingsBoard platform.

Overview

Agents can:

• Get all devices in aiiotlayer
• Get device details and telemetry data
• Get water meter readings (temperature, water flow, water level)
• List all dashboards
• Query device-specific telemetry values
• Manage devices, assets, customers, alarms, and users

Setup

Step 1: Copy Files

Copy the integration files to the active plugins directory:

# Linux/Mac
mkdir -p backend/storage/plugins/agent-skills/aiiotlayer
cp -r path/to/aiiotlayer/* backend/storage/plugins/agent-skills/aiiotlayer/

# Windows (PowerShell)
New-Item -ItemType Directory -Force -Path "backend\storage\plugins\agent-skills\aiiotlayer"
Copy-Item -Path "path\to\aiiotlayer\*" -Destination "backend\storage\plugins\agent-skills\aiiotlayer\" -Recurse -Force

Step 2: Get API Key

1. Log in to aiiotlayer UI at http://localhost:8080
2. Navigate to System Settings → Security Settings → API Keys
3. Click "+" or "Add API Key" to create a new API key
4. Enter a name (e.g., "AINexLayer Integration")
5. Select TENANT_ADMIN scope (minimum)
6. Copy the API key (starts with tb_)

Important: This plugin only works with API keys (starting with tb_), not JWT tokens.

Step 3: Configure in AINexLayer

1. Navigate to Workspace Settings → Agent Skills
2. Find AIIOTlayer in the list
3. Configure:
   • TB_BASE_URL: Base URL of your aiiotlayer instance (e.g., http://localhost:8080)
   • TB_API_KEY: Your API key (must start with tb_)
4. Save configuration

Step 4: Restart AINexLayer

Restart your AINexLayer server for changes to take effect.

Usage Examples

User: "Show me all devices in aiiotlayer"
AI: [Calls get_devices and displays list]

User: "What is the current temperature?"
AI: [Calls get_temperature and displays value]

User: "Show me water meter readings"
AI: [Calls get_water_meter_readings and displays all readings]

User: "What is the water flow?"
AI: [Calls get_water_flow and displays value]

User: "List all dashboards"
AI: [Calls get_dashboards and displays list]

Available Operations

Devices (Full CRUD)

• get_devices - List all devices
• get_device - Get specific device details by ID
• create_device - Create a new device
• update_device - Update an existing device
• delete_device - Delete a device

Assets (Full CRUD)

• get_assets - List all assets
• get_asset - Get specific asset details by ID
• create_asset - Create a new asset
• update_asset - Update an existing asset
• delete_asset - Delete an asset

Customers (Full CRUD)

• get_customers - List all customers
• get_customer - Get specific customer details by ID
• create_customer - Create a new customer
• update_customer - Update an existing customer
• delete_customer - Delete a customer

Telemetry (Read-only)

• get_device_telemetry - Get telemetry data for a device
• get_water_meter_readings - Get all water meter readings
• get_temperature - Get current temperature reading
• get_water_flow - Get current water flow reading
• get_water_level - Get current water level reading

Alarms

• get_alarms - List all alarms (can filter by entity type, entity ID, status)
• get_alarm - Get specific alarm details
• create_alarm - Create a new alarm for an entity
• ack_alarm - Acknowledge an alarm
• clear_alarm - Clear an alarm

Dashboards (Read-only)

• get_dashboards - List all dashboards in aiiotlayer

Troubleshooting

Error: "aiiotlayer base URL is not configured"

• Check that TB_BASE_URL is set in the plugin configuration
• Verify the URL is correct (no trailing slash)
• Ensure the URL is accessible from AINexLayer server

Error: "aiiotlayer API key is not configured"

• Make sure TB_API_KEY is set in the plugin configuration
• Verify the API key is correct (must start with tb_)
• This plugin only works with API keys, not JWT tokens
• Get a new API key from: System Settings → Security Settings → API Keys

Error: "Device not found"

• Check that the device ID is correct
• Verify the device exists in aiiotlayer
• Ensure the API key has permissions to view the device

Authentication Errors (401/403)

• Verify API key is correct and starts with tb_
• Check API key permissions in aiiotlayer
• Ensure API key has TENANT_ADMIN scope
• Try creating a new API key