@idi-fly/node-red-idi-fly

Node-RED nodes for publishing drone telemetry data to IDI-FLY subscribers via WebSocket.

Features

• Automatic Authentication: OAuth 2.0 M2M token fetching with automatic refresh
• WebSocket Management: Auto-reconnect with exponential backoff
• Offline Handling: Messages queued when disconnected, sent on reconnect
• Keep-Alive: Automatic ping to maintain connection
• Easy Integration: Simple drag-and-drop nodes for Node-RED

Installation

From npm

cd ~/.node-red
npm install @idi-fly/node-red-idi-fly

Then restart Node-RED.

From Source

cd ~/.node-red
npm install /path/to/node-red-idi-fly

Or use npm link for development:

cd /path/to/node-red-idi-fly
npm link

cd ~/.node-red
npm link @idi-fly/node-red-idi-fly

Prerequisites

1. IDI-FLY Integration API deployed
2. Cognito App Client with:
   • client_credentials grant type enabled
   • stream:publish scope assigned
3. API Key from API Gateway

Nodes

idi-fly-publish

Publishes data to IDI-FLY WebSocket subscribers.

Input

| Property | Type | Description | |----------|------|-------------| | msg.payload | object | Data to publish (required) | | msg.resourceId | string | Override resource ID (optional) | | msg.dataType | string | Override data type (optional) |

Output

| Property | Type | Description | |----------|------|-------------| | msg.payload | object | Original payload (pass-through) | | msg._idifly | object | Publish metadata | | msg._idifly.published | boolean | True if sent immediately | | msg._idifly.queued | boolean | True if queued for later | | msg._idifly.resourceId | string | Resource ID used | | msg._idifly.timestamp | string | ISO timestamp |

idi-fly-config

Configuration node (singleton) that manages authentication and WebSocket connection.

Settings

| Setting | Description | Default | |---------|-------------|---------| | REST API URL | Token endpoint base URL | Required | | WebSocket URL | WebSocket API URL | Required | | API Key | x-api-key header value | Required | | Client ID | Cognito App Client ID | Required | | Client Secret | Cognito App Client Secret | Required | | Resource ID | Default resource identifier | Required | | Auto Connect | Connect on deploy | true | | Reconnect Interval | Base reconnect delay (ms) | 5000 | | Ping Interval | Keep-alive interval (ms) | 30000 |

Quick Start

1. Drag an idi-fly publish node onto your flow
2. Double-click to configure
3. Click the pencil icon to create a new IDI-FLY connection
4. Enter your credentials:
   • REST API URL: https://xxx.execute-api.eu-west-2.amazonaws.com/dev
   • WebSocket URL: wss://xxx.execute-api.eu-west-2.amazonaws.com/dev
   • API Key: Your API Gateway key
   • Client ID: Cognito App Client ID
   • Client Secret: Cognito App Client Secret
   • Resource ID: e.g., device-001
5. Connect an inject or function node to provide data
6. Deploy

Example Flow

Import the example from Menu > Import > Examples > @idi-fly/node-red-idi-fly.

Or use this simple flow:

[Inject] -> [Function: Format Data] -> [idi-fly-publish] -> [Debug]

Function Node Example

// Format telemetry data for IDI-FLY
msg.payload = {
    type: 'telemetry',
    latitude: 51.5074,
    longitude: -0.1278,
    altitude: 120,
    battery: 85,
    speed: 15.5,
    heading: 270
};

return msg;

Integration Examples

From MQTT

[MQTT In] -> [Function: Parse] -> [idi-fly-publish]

From Serial/MAVLink

[Serial In] -> [Function: Parse MAVLink] -> [idi-fly-publish]

From HTTP

[HTTP In] -> [idi-fly-publish] -> [HTTP Response]

Message Format

The node sends messages in this format:

{
    "action": "publish",
    "resourceId": "device-001",
    "data": {
        "type": "telemetry",
        "latitude": 51.5074,
        "longitude": -0.1278,
        "altitude": 120,
        "battery": 85
    }
}

Status Indicators

| Status | Meaning | |--------|---------| | 🟢 Green dot | Connected and ready | | 🟡 Yellow ring | Connecting or message queued | | 🔴 Red ring | Disconnected | | 🔴 Red dot | Error |

Token Management

• Tokens are fetched automatically on first connection
• Tokens are refreshed 5 minutes before expiry
• If token fetch fails, retries with exponential backoff (1s, 2s, 4s)
• WebSocket reconnects automatically after token refresh

Error Handling

"Permission denied: stream:publish scope required"

Your Cognito App Client needs the stream:publish scope:

1. Go to AWS Console > Cognito > User Pools
2. Select your user pool > App Integration
3. Edit your Resource Server to add the stream:publish scope
4. Edit your App Client to include the scope

"Token expired"

Tokens expire after 1 hour. The node handles this automatically, but if you see persistent errors:

1. Check your Cognito configuration
2. Verify Client ID and Secret are correct
3. Check the Node-RED log for detailed errors

"Max reconnect attempts reached"

The WebSocket has failed to connect after 10 attempts:

1. Check your WebSocket URL
2. Verify the API is deployed and accessible
3. Check network connectivity
4. Restart the flow

Development

Testing Locally

# Install dependencies
npm install

# Link for local development
npm link

# In your Node-RED directory
npm link @idi-fly/node-red-idi-fly

Running Tests

npm test

License

MIT

Support

• Documentation: IDI-FLY Integration API Docs
• Issues: GitHub Issues