Overview
The I/O Ports API provides access to manage and monitor the state of input/output ports on connected devices. This API allows developers to query the current state of multiple I/O ports and update their state if needed. It is useful in scenarios such as managing the operational status of connected devices or sensors in a video surveillance or monitoring system.
Key Use Cases:
Querying the status of multiple I/O ports in real-time.
Changing the state of a specific I/O port to trigger actions on connected devices.
Prerequisites:
Devices related to the API features covered in this article, including I/O network relays, must first be registered with an Arcules gateway appliance. These devices should also be online and have an active internet connection.
Gateway appliance(s) should be online and have an active internet connection.
Users must have the following roles assigned in the Arcules web portal:
API User Role: To be able to use both I/O and Audio functionalities through our API.
I/O Relay Operator Role: To be able to use the I/O functionalities of our API.
API Endpoint
Endpoint 1: Query I/O Ports Status
HTTP Method: GET
Authentication: OAuth 2.0 Bearer Token
Request Parameters
Parameter | Type | Description | Required |
portIds | string | A comma-separated list of unique port IDs to query the state for. | Yes |
Sample Request
GET /v1/ioports?portIds=72af2eb5-e0c6-44b7-a122-e34b89e8880b,2945cd45-3197-4b5c-a01f-7c6ae2cd132b
Host: msapi.arcules.com
Authorization: Bearer {token}
Sample Response
{
"2945cd45-3197-4b5c-a01f-7c6ae2cd132b": {
"state": "low",
"lastUpdated": 1726183188281
},
"72af2eb5-e0c6-44b7-a122-e34b89e8880b": {
"state": "low",
"lastUpdated": 1726183188281
}
}
Endpoint 2: Update I/O Port State
HTTP Method: PATCH
Authentication: OAuth 2.0 Bearer Token
Request Parameters
Parameter | Type | Description | Required |
portId | string | The unique ID of the I/O port to be updated. | Yes |
Sample Request
PATCH /v1/ioport/ad545e36-1179-4013-a901-af5550e6e113
Host: msapi.arcules.com
Authorization: Bearer {token}
Content-Length: 20
{
"state": "pulse",
"duration": 500
}
Sample Response
204 No Content
Error Handling
Error Code | Message | Description |
200 | OK | The request was successful. |
204 | No Content | The request was successful but there is no content to send for this request. |
400 | Bad Request | The request was invalid or cannot be processed. |
401 | Unauthorized | Missing or invalid JWT. |
403 | Forbidden | API users lack the necessary permissions. |
404 | Not Found | The requested resource could not be found. |
429 | Too Many Requests | API rate limit has been exceeded. |
5xx | Server Error | The server encountered an issue processing the request. |
Additional Resources
FAQ
Q: How do I authenticate?
A: Use your OAuth 2.0 Bearer Token in the request header. See the Authentication Guide for more details.
Q: How can I obtain the portId value?
A: You can retrieve the portId
values from the response of the /v1/devices endpoint.
Q: Can I retrieve historical states of an I/O port?
A: No, the I/O Ports API only provides the current state of the port. For historical data, you'll need to implement your own logging mechanism or use additional services.
Q: How frequently are port states updated?
A: Port states are updated in real-time, but lastUpdated
indicates the timestamp (in milliseconds since the epoch) of the most recent update.
Q: What states can I set for the I/O ports?
A: You can set the following states for the I/O ports:
high
: The output port is set to an active state.low
: The output port is set to an inactive state.pulse
: A temporary pulse is applied to the port. When using this state, you must also specify the duration in seconds, which determines how long the pulse should last.
Q: How do I know if the state change was successful?
A: For a successful state change, the API will return a 204 No Content
response, indicating the state was updated without errors. If there was an issue, you'll receive an error code with additional details.
Q: What happens if I don't include a duration with the pulse state?
A: If you set the state to pulse without specifying a duration, the request will fail, and you will receive a 400 Bad Request
response indicating that the duration parameter is missing.
Q: Can I revert the state of an I/O port after sending a pulse?
A: The pulse state automatically reverts to the previous state after the specified duration has passed. No additional action is needed to reset it.