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).

Search

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

List or search for existing modules.

Query Parameters

Name	Type	Description
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.

200

{
  "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

Name	Type	Description
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

200 Successful creations will return the full module.

{
  "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"
}

406 Missing or invalid module configuration.

{
  "dependency_id": ["can't be blank"]
}

Retrieve

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

Retrieve all metadata associated with a module.

Path Parameters

Name	Type	Description
id	string	ID of the modules to retrieve.

200

{
  "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"
}

404

Update

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

Updates module attributes or configuration.

Path Parameters

Name	Type	Description
id	string	ID of the module to update.

Request Body

Name	Type	Description
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

200 Module updated.

{
  "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"
}

403 The user does not have permissions to update this module.

404 The passed module ID does not exist.

406 Validation error.

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

Name	Type	Description
id	string	ID of the module to delete.

200

403

404

Interaction

Start

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

Starts a module on it's associated control node.

Path Parameters

Name	Type	Description
id	string	ID of the module to start.

200 Module started.

403

404

500 An error occurred that prevented the module from starting.

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

Name	Type	Description
id	string	ID of the module to stop.

200

403

404

Ping

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

Performs a connectivity check with the associated device or service.

Path Parameters

Name	Type	Description
id	string	ID of the module to check.

200

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

406 The module specified is a logic module.

State

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

Gets the state information exposed by a module.

Path Parameters

Name	Type	Description
id	string	ID of the module to query.

Query Parameters

Name	Type	Description
lookup	string	Status key of interest. If included, the response filters to this value.

200

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