API Documentation

REST API reference for the DC Next IoT Gateway Core Service (Port 8080)

The DC Next Core API provides a comprehensive REST interface for managing and monitoring IoT devices connected through the DC Next gateway. This documentation covers all available endpoints for device management, system information retrieval, real-time data streaming, and more.

Base URL: http://<gateway-ip>:8080

Authentication

All API requests to the DC Next Core API require HTTP Basic Authentication. The gateway uses a username and password that are established during initial gateway configuration.

Credentials

Username: admin
Password: Set during gateway initialization

Authorization Header

Include the Authorization header in all requests with a Base64-encoded username:password combination.

Example Header

Authorization: Basic YWRtaW46cGFzc3dvcmQ=

Note: The Base64 string decodes to "admin:password" where password is your configured gateway password.

Integration Architecture — Best Practice

The correct way to integrate with the DC Next Gateway is a two-channel architecture: a persistent Streaming connection for receiving live device data, combined with standard REST calls for sending commands. This applies to all radio protocols — EnOcean, Bluetooth LE, and LoRaWAN.

Step 1: Open the Streaming API

Establish a persistent HTTP connection to GET /devices?streaming=true. This uses chunked transfer encoding (Server-Sent Events). Once connected, the gateway pushes every device state change in real-time as a JSON object — no polling required.

GET /devices?streaming=true HTTP/1.1
Host: gateway-ip:8080
Authorization: Basic YWRtaW46cGFzc3dvcmQ=
Accept: application/json

The gateway will keep this connection open and stream JSON events whenever any device transmits data. Each event contains the device ID, updated state values, signal strength, and timestamp.

Step 2: Send Commands via REST

In parallel, use standard REST calls to send commands to devices. Typically this means PUT /devices/{id} to control actuators (switch relays, set dimmer levels, adjust setpoints). These are classic request-response calls.

PUT /devices/01A2B3C4 HTTP/1.1
Host: gateway-ip:8080
Authorization: Basic YWRtaW46cGFzc3dvcmQ=
Content-Type: application/json

{ "state": { "relay": "on" } }

⚠ Common Anti-Pattern: Many integrators poll GET /devices/{id}/states every few seconds to check for state changes. This is fundamentally wrong. Polling creates unnecessary load, introduces latency, and misses events between polling intervals. Always use the Streaming API for receiving device data, and REST only for sending commands.

Streaming Channel

Gateway → Client
Live device events
GET /devices?streaming=true

REST Commands

Client → Gateway
Control actuators
PUT /devices/{id}

Response Format

All API responses follow a consistent JSON format with a standard header containing status information and a body containing the response data.

Response Structure

{
  "header": {
    "code": "S1000",
    "httpStatus": 200,
    "message": "OK"
  },
  "body": {
    "key": "value"
  }
}

Header Fields

Field	Type	Description
`code`	string	Status code (S for success, E for error)
`httpStatus`	integer	HTTP status code (200, 400, 401, 404, 500, etc.)
`message`	string	Human-readable status message

Error Codes

The following error codes may be returned in API responses. Check both the code and httpStatus fields to determine the type of error.

Code	HTTP Status	Description
`S1000`	200	Success - Request completed successfully
`E2000`	400	Bad Request - Invalid parameters or malformed request
`E2002`	401	Unauthorized - Invalid or missing authentication credentials
`E2501`	404	Not Found - Requested resource does not exist
`E2502`	409	Conflict - Resource already exists or operation conflicts with current state
`E8000`	500	Internal Server Error - An unexpected error occurred on the gateway

System Information

Retrieve gateway identification, status, and configuration information.

GET /system/info

Returns gateway identification and version information including radio frequency, supported protocols, and uptime.

Response Body

{
  "baseId": "FFAB1234",
  "eurid": "052A03C6",
  "frequency": "868.3 MHz",
  "version": "2.1.0.4567",
  "protocols": [
    "EnOcean",
    "LoRa",
    "WM-Bus"
  ],
  "uptime": "5d 12h 30m"
}

GET /system/status

Initiates an internal system test suite. The results can be retrieved using the /system/results endpoint.

GET /system/results

Retrieves the results from the last system status check initiated by /system/status.

GET /system/uptime

Returns the gateway uptime in milliseconds since last startup.

Response Body

{
  "uptime": 486600000
}

Devices

Manage and monitor all IoT devices paired with the DC Next gateway.

GET /devices

List all paired devices with their current status and signal strength.

Query Parameters

Parameter	Type	Description
`lod`	string	Level of detail: `FULL` or `SUMMARY` (default: SUMMARY)
`radio`	string	Filter by radio type: `enocean` or `lora` (default: all)
`streaming`	boolean	If true, returns Server-Sent Events stream instead of static list

Response Body

{
  "devices": [
    {
      "id": "01A2B3C4",
      "friendlyId": "Living Room Switch",
      "eep": "F6:02:01",
      "manufacturer": "EnOcean GmbH",
      "rssi": -65
    }
  ]
}

GET /devices/{id}

Retrieve detailed information for a specific device.

Path Parameters

Parameter	Type	Description
`id`	string	Device ID in hexadecimal format (e.g., 01A2B3C4)

Example Request:

GET /devices/01A2B3C4

GET /devices/{id}/states

Get current state values for a device, including button presses, sensor readings, and other telemetry data.

Response Body

{
  "states": [
    {
      "key": "buttonA",
      "value": "pressed",
      "meaning": "Button A pressed",
      "timestamp": "2026-03-23T14:30:00Z"
    }
  ]
}

GET /devices/{id}/parameters

Retrieve configurable parameters for a remote device. Parameters vary depending on device type and EEP profile.

PUT /devices/{id}/parameters

Update device parameters. Send a JSON object with parameter names and new values.

Request Body

{
  "parameterName": "value",
  "anotherParameter": 42
}

GET /devices/{id}/linktable

Retrieve the link table for bidirectional EnOcean devices. This shows device relationships and communication paths.

GET /devices/{id}/calendar

Get scheduled actions and automation rules configured for a device.

PUT /devices/{id}/calendar

Update device calendar and scheduled automation rules. Allows you to define time-based actions for the device.

DELETE /devices/{id}

Remove a device from the gateway. The device can be re-paired at any time.

Note: This action cannot be undone, but the device can be re-paired by initiating a pairing sequence on the device.

Profiles

Access supported device profiles and specifications.

GET /profiles

List all supported EEP (EnOcean Equipment Profile) and device profiles available on the gateway.

Query Parameters

Parameter	Type	Description
`radio`	string	Filter by radio type: `enocean` or `lora`

Response Body (Sample)

{
  "profiles": [
    {
      "id": "F6:02:01",
      "title": "Rocker Switch, 2-gang",
      "description": "2-channel rocker switch with On/Off control"
    }
  ]
}

GET /profiles/{eep}

Get detailed technical specifications for a specific profile, including function definitions and data structures.

Path Parameters

Parameter	Type	Description
`eep`	string	EEP profile ID (e.g., F6:02:01)

Query Parameters

Parameter	Type	Description
`variation`	string	Profile variation (optional)
`version`	string	Profile version (optional)

Example Request:

GET /profiles/F6:02:01?variation=1&version=1

GET /profiles/{eep}.pdf

Download the profile specification as a PDF document with detailed technical information.

GET /profiles/{eep}.html

View the profile specification as an interactive HTML page in your browser.

Streaming / Real-Time

Receive real-time device state changes using Server-Sent Events (SSE).

GET /devices?streaming=true

Opens a persistent Server-Sent Events stream for all device state changes. The connection remains open and sends updates whenever any paired device changes state.

Query Parameters

Parameter	Type	Description
`streaming`	boolean	Must be set to `true` to enable streaming mode

Response Format

Response uses chunked transfer encoding with newline-delimited JSON events:

data: {
  "deviceId": "01A2B3C4",
  "state": "pressed",
  "timestamp": "2026-03-23T14:30:45Z"
}

data: {
  "deviceId": "05D4E6F7",
  "state": "released",
  "timestamp": "2026-03-23T14:30:46Z"
}

Note: SSE streams are ideal for real-time applications. The connection automatically reconnects if interrupted.

GET /devices/{id}?streaming=true

Opens a persistent Server-Sent Events stream for state changes from a specific device only. Updates arrive whenever the device state changes.

Path Parameters

Parameter	Type	Description
`id`	string	Device ID in hexadecimal format

Example Request:

GET /devices/01A2B3C4?streaming=true

Products

GET /productIds

List all supported product configurations and their identifiers. Each product can be assigned to devices during pairing.

Response Body (Sample)

{
  "products": [
    {
      "id": "PROD_001",
      "name": "Smart Light Switch",
      "category": "Lighting"
    },
    {
      "id": "PROD_002",
      "name": "Temperature Sensor",
      "category": "Sensors"
    }
  ]
}

Help

GET /help

Returns the built-in API help page with endpoint information and examples. Useful for discovering available endpoints from within the gateway itself.