Modules

The /modules endpoint provides creation, management and direct interaction with modules outside of a system context. For more information on the role that modules play, see:

Modules

Model

Attribute

Type

Description

id

string

A universally unique ID for this module.

dependency_id

string

ID of the driver that defines this module.

control_system_id

string

ID of the system this module is bound to (logic modules only).

edge_id

string

ID of the preferred engine node to run on.

ip

string

IP address or resolvable hostname of the device this module connects to.

tls

boolean

True if the device communicates securely.

udp

boolean

Protocol uses UDP rather that TCP.

port

integer

The TCP or UDP port that the associated device communicates on.

makebreak

boolean

If enabled, provides an ephemeral connection that disconnects during idle periods.

uri

string

The based URI of the remote service (service modules only).

custom_name

string

The modules class name (Display, Lighting etc) if it should differ from the default defined in the dependency.

settings

object

A JSON object containing module configuration.

updated_at

integer

Timestamp of last update.

created_at

integer

Timestamp of creation.

role

integer

The module type. One of:

0 ssh

1 device

2 service

3 logic

notes

string

Markdown formatted text that describes this module.

connected

boolean

Flag for connectivity state.

running

boolean

Module start/stop state.

ignore_connected

boolean

If enabled, system metrics ignore connectivity state.

ignore_startstop

boolean

If enabled, system level start and stop actions are ignored. This is recommended for modules shared by many systems (e.g. a lighting gateway).

GET https://example.com/api/control/modules

List or search for existing modules.

Query Parameters

NameTypeDescription

q

string

A search filter to apply.

limit

integer

(default 20) Max results to return.

offset

integer

The offset within the result set.

system_id

string

Return modules associated with the specified system.

dependency_id

string

Return modules that are an instance of the specified dependency.

{
  "total": 1,
  "results": [
    {
      "dependency_id": "dep-wJHShR4Ffa",
      "control_system_id": null,
      "edge_id": "edge-E9vIruSZ",
      "ip": "10.45.6.3",
      "tls": false,
      "udp": false,
      "port": 8192,
      "makebreak": false,
      "uri": null,
      "custom_name": null,
      "settings": {},
      "updated_at": 1572412023,
      "created_at": 1572392714,
      "role": 1,
      "connected": true,
      "running": true,
      "notes": null,
      "ignore_connected": false,
      "ignore_startstop": false,
      "id": "mod-wJHYeHm6Yn"
    }
  ]
}

Queries default to searching for any of the entered terms (words). A small query language provides the ability to structure complex queries.

Operator

Action

+

Matches both terms.

`

`

Matches either terms.

-

Negates a single token.

"

Wraps tokens to form a phrase.

( and )

Provide precedence.

~N

Specifies edit distance (fuzziness) after a word.

~N

Specifies slop amount (deviation) after a phrase.

Management

Create

POST https://example.com/api/control/modules

Creates a new module.

Request Body

NameTypeDescription

dependency_id

string

edge_id

string

control_system_id

string

required for logic modules

ip

string

required for ssh and device modules

udp

boolean

port

integer

makebreak

boolean

uri

string

required for service modules

custom_name

string

settings

object

notes

string

ignore_connected

boolean

ignore_startstop

boolean

{
  "dependency_id": "dep-wJHShR4Ffa",
  "control_system_id": null,
  "edge_id": "edge-E9vIruSZ",
  "ip": "10.45.6.3",
  "tls": false,
  "udp": false,
  "port": 8192,
  "makebreak": false,
  "uri": null,
  "custom_name": null,
  "settings": {},
  "updated_at": 1572412023,
  "created_at": 1572412023,
  "role": 1,
  "connected": true,
  "running": true,
  "notes": null,
  "ignore_connected": false,
  "ignore_startstop": false,
  "id": "mod-wJHYeHm6Yn"
}

Retrieve

GET https://example.com/api/control/modules/{id}

Retrieve all metadata associated with a module.

Path Parameters

NameTypeDescription

id

string

ID of the modules to retrieve.

{
  "dependency_id": "dep-wJHShR4Ffa",
  "control_system_id": null,
  "edge_id": "edge-E9vIruSZ",
  "ip": "10.45.6.3",
  "tls": false,
  "udp": false,
  "port": 8192,
  "makebreak": false,
  "uri": null,
  "custom_name": null,
  "settings": {},
  "updated_at": 1572412023,
  "created_at": 1572412023,
  "role": 1,
  "connected": true,
  "running": true,
  "notes": null,
  "ignore_connected": false,
  "ignore_startstop": false,
  "id": "mod-wJHYeHm6Yn"
}

Update

PUT https://example.com/api/control/modules/{id}

Updates module attributes or configuration.

Path Parameters

NameTypeDescription

id

string

ID of the module to update.

Request Body

NameTypeDescription

control_system_id

string

edge_id

string

ip

string

udp

boolean

port

integer

makebreak

boolean

uri

string

custom_name

string

settings

object

notes

string

ignore_connected

boolean

ignore_startstop

boolean

{
  "dependency_id": "dep-wJHShR4Ffa",
  "control_system_id": null,
  "edge_id": "edge-E9vIruSZ",
  "ip": "10.45.6.3",
  "tls": false,
  "udp": false,
  "port": 8192,
  "makebreak": false,
  "uri": null,
  "custom_name": null,
  "settings": {},
  "updated_at": 1572412023,
  "created_at": 1572414543,
  "role": 1,
  "connected": true,
  "running": true,
  "notes": null,
  "ignore_connected": false,
  "ignore_startstop": false,
  "id": "mod-wJHYeHm6Yn"
}

Delete

DELETE https://example.com/api/control/modules/{id}

Removes a module. Modules that are associated with multiple systems be removed from all.

Path Parameters

NameTypeDescription

id

string

ID of the module to delete.

Interaction

Start

POST https://example.com/api/control/modules/{id}/start

Starts a module on it's associated control node.

Path Parameters

NameTypeDescription

id

string

ID of the module to start.

Stop

POST https://example.com/api/control/modules/{id}/stop

Stops the module. Exposed state will still be available but will not update.

Path Parameters

NameTypeDescription

id

string

ID of the module to stop.

Ping

POST https://example.com/api/control/modules/{id}/ping

Performs a connectivity check with the associated device or service.

Path Parameters

NameTypeDescription

id

string

ID of the module to check.

{
  "host": "10.45.5.2",
  "pingable": true,
  "warning": null,
  "exception": null
}

State

GET https://example.com/api/control/modules/{id}/state

Gets the state information exposed by a module.

Path Parameters

NameTypeDescription

id

string

ID of the module to query.

Query Parameters

NameTypeDescription

lookup

string

Status key of interest. If included, the response filters to this value.

{
  "foo": "abc",
  "bar": 42
}

Last updated