Manage fieldbus device protocols

Create, list, read, and delete the fieldbus device protocols that map the data of Modbus, CAN bus, and CANopen devices.

Use with an AI agent

This page is the agent skill cumulocity-manage-device-protocols. Save it as cumulocity-manage-device-protocols/SKILL.md in the skills folder of your agent: .agents/skills/ for Codex, GitHub Copilot, Cursor, and Gemini CLI, or .claude/skills/ for Claude Code. It builds on cumulocity-authentication: install that skill too.

View SKILL.md All skills

POST /inventory/managedObjects Create one or multiple managed objects
GET /inventory/managedObjects Retrieve all managed objects
GET /inventory/managedObjects/{id} Retrieve a specific managed object
DELETE /inventory/managedObjects/{id} Remove a specific managed object

Managing device types
Configuring fieldbus device protocols in Cloud Fieldbus

A device protocol, also called device type, describes the data of a type of device. Fieldbus device protocols for Modbus, CAN bus, and CANopen devices are managed objects in the inventory. They have the following properties:

The marker fragment c8y_IsDeviceType. The Device protocols page of the Device Management application lists all managed objects with this fragment.
The property fieldbusType, which names the fieldbus family, for example modbus.
The fragments c8y_Coils and c8y_Registers, which contain the coil and register definitions of the protocol.

This skill covers the device protocol as a managed object. It does not describe the coil and register definitions. To configure them, see Configuring fieldbus device protocols. The Device protocols page also shows LWM2M, OPC UA, and LPWAN protocols. Their own services manage them, so this skill does not cover them.

Requirements

SKILLS:

Authenticate REST API requests

ROLES & PERMISSIONS:

To create and delete device protocols: ROLE_INVENTORY_ADMIN
To read device protocols: ROLE_INVENTORY_READ

The examples use <protocol_id> for the ID of the device protocol.

To create a device protocol

Send a Create one or multiple managed objects request:

POST /inventory/managedObjects
Content-Type: application/json
Accept: application/json

{
  "name": "My Modbus device protocol",
  "type": "c8y_ModbusDeviceType",
  "fieldbusType": "modbus",
  "c8y_IsDeviceType": {},
  "c8y_Coils": [],
  "c8y_Registers": []
}

The request creates a protocol without coils and registers. Add them in the Device Management application, see Configuring fieldbus device protocols.

The platform returns HTTP 201 and the device protocol with its id. Note the id as <protocol_id>.

To list the device protocols

Send a Retrieve all managed objects request with a query for the fragment c8y_IsDeviceType. This is the query that the Device Management application uses:

GET /inventory/managedObjects?query=$filter=has(c8y_IsDeviceType)&pageSize=2000

URL-encode the value of the query parameter.

The platform returns HTTP 200. The managedObjects array contains the device protocols with their id, name, and fieldbusType.

To read a device protocol

Send a Retrieve a specific managed object request:

GET /inventory/managedObjects/<protocol_id>

The platform returns HTTP 200 and the device protocol with its name, type, fieldbusType, coils, and registers. If the response does not contain the fragment c8y_IsDeviceType, the managed object is not a device protocol.

If the platform returns HTTP 404, the device protocol does not exist.

To delete a device protocol

Info

Deleting a device protocol does not change the devices that use it. Their fieldbus fragments still refer to the deleted protocol.

Send a Remove a specific managed object request:

DELETE /inventory/managedObjects/<protocol_id>

The platform returns HTTP 204. If the deletion takes longer than 30 seconds, the platform returns HTTP 202 and completes it in the background. If the platform returns HTTP 404, the device protocol does not exist anymore.

In the Device Management application, you manage device protocols on the Device protocols page, see Managing device types.