# 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:

{% content-ref url="../../key-concepts/modules" %}
[modules](https://engine.place.technology/key-concepts/modules)
{% endcontent-ref %}

## 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` | <p>The module type. One of:</p><p><code>0</code> ssh</p><p><code>1</code> device</p><p><code>2</code> service</p><p><code>3</code> logic</p> |
| ---- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------- |

| 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

<mark style="color:blue;">`GET`</mark> `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. |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "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"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

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

<mark style="color:green;">`POST`</mark> `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 |                                     |

{% tabs %}
{% tab title="200 Successful creations will return the full module." %}

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

{% endtab %}

{% tab title="406 Missing or invalid module configuration." %}

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

{% endtab %}
{% endtabs %}

## Retrieve

<mark style="color:blue;">`GET`</mark> `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. |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}

{% tab title="404 " %}

```
```

{% endtab %}
{% endtabs %}

## Update

<mark style="color:orange;">`PUT`</mark> `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 |             |

{% tabs %}
{% tab title="200 Module updated." %}

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

{% endtab %}

{% tab title="403 The user does not have permissions to update this module." %}

```
```

{% endtab %}

{% tab title="404 The passed module ID does not exist." %}

```
```

{% endtab %}

{% tab title="406 Validation error." %}

```
```

{% endtab %}
{% endtabs %}

## Delete

<mark style="color:red;">`DELETE`</mark> `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. |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}

{% tab title="403 " %}

```
```

{% endtab %}

{% tab title="404 " %}

```
```

{% endtab %}
{% endtabs %}

## Interaction

## Start

<mark style="color:green;">`POST`</mark> `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. |

{% tabs %}
{% tab title="200 Module started." %}

```
```

{% endtab %}

{% tab title="403 " %}

```
```

{% endtab %}

{% tab title="404 " %}

```
```

{% endtab %}

{% tab title="500 An error occurred that prevented the module from starting." %}

```
```

{% endtab %}
{% endtabs %}

## Stop

<mark style="color:green;">`POST`</mark> `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. |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}

{% tab title="403 " %}

```
```

{% endtab %}

{% tab title="404 " %}

```
```

{% endtab %}
{% endtabs %}

## Ping

<mark style="color:green;">`POST`</mark> `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. |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}

{% tab title="406 The module specified is a logic module." %}

```
```

{% endtab %}
{% endtabs %}

## State

<mark style="color:blue;">`GET`</mark> `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. |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}
{% endtabs %}