MQTT API Documentation

Select a version:

SICON.OS Public MQTT API 1.0

application/json

The SICON.OS Public MQTT API serves live changes for devices and their associated data such as events, production status, maintenance status, new parameter values or reports.

How to connect:

For development purposes, you can use the SICON.OS domain provided by your installation (sicon-test.local in the examples below)
Once deployed as app, we will provide the environment variables MQTT_HOST and MQTT_PORT to your container
For external integrations, use the WebSocket protocol to exchange data securely

Servers

sicon-test.local:{port}mqttunsecure
Test broker

port
required
string
Secure connection (TLS) is available through port 443 via WebSocket

Default value:"1883"
sicon-test.local:{port}wssecure
Test broker

port
required
string
WebSocket may have HTTP overhead and reduced feature set depending on library

Default value:"443"

Operations

SUB device/:ID/postReport
Reports are device datapoints that are captured after every cycle. X and Y values represent the axis they belong to. X is additional to time, Y are individual values. If the device does not provide cyclic data, reports are triggered every two seconds Reports have to be configured via Sicon Device Description

ID
required
integer
uid: ID
The ID of the device. More information about the device can be obtained via the Rest API
Accepts the following message:
report
object
uid: report
X_1
string
Primary cycle indicator

X_2
string
secondary cycle indicator, e.g. erasable or part cycle

X_3
string
secondary cycle indicator, e.g. erasable or part cycle

X_4
string
secondary cycle indicator, e.g. erasable or part cycle

Y_1
string
Y_2
string
Y_3
string
Y_4
string
Y_5
string
Y_6
string
Y_7
string
Y_8
string
Y_9
string
Y_10
string
Y_11
string
Y_12
string
Y_13
string
Y_14
string
Y_15
string
Y_16
string
Y_17
string
Y_18
string
Y_19
string
Y_20
string
Y_21
string
Y_22
string
Y_23
string
Y_24
string
Y_25
string
Y_26
string
Y_27
string
Y_28
string
Y_29
string
Y_30
string
Additional properties are allowed.
Examples
{ "X_1": "string", "X_2": "string", "X_3": "string", "X_4": "string", "Y_1": "string", "Y_2": "string", "Y_3": "string", "Y_4": "string", "Y_5": "string", "Y_6": "string", "Y_7": "string", "Y_8": "string", "Y_9": "string", "Y_10": "string", "Y_11": "string", "Y_12": "string", "Y_13": "string", "Y_14": "string", "Y_15": "string", "Y_16": "string", "Y_17": "string", "Y_18": "string", "Y_19": "string", "Y_20": "string", "Y_21": "string", "Y_22": "string", "Y_23": "string", "Y_24": "string", "Y_25": "string", "Y_26": "string", "Y_27": "string", "Y_28": "string", "Y_29": "string", "Y_30": "string" }

This example has been generated automatically.
PUB device/:ID/startObservation
Command to request sending of postObservation for 10 seconds

ID
required
integer
uid: ID
The ID of the device. More information about the device can be obtained via the Rest API

Accepts the following message:
empty object
Examples
SUB device/:ID/postObservation
Observation data represents all live values from the group Observation. Has to be started with startObservation

ID
required
integer
uid: ID
The ID of the device. More information about the device can be obtained via the Rest API
Accepts the following message:
observation
object
uid: observation
object
this key is repeated as often as values exist for observation

Unit
string
unit of the associated value. e.g. mm, C°, V, A

Value
string
current value

Additional properties are allowed.
Additional properties are allowed.
Examples
{ ":MQTTLabel": { "Unit": "string", "Value": "string" } }

This example has been generated automatically.
PUB device/:ID/putStatData
Write parameters to a Index.Subindex tuple with the desired value.

ID
required
integer
uid: ID
The ID of the device. More information about the device can be obtained via the Rest API
Accepts the following message:
putstatdata
object
uid: putstatdata
Index.Subindex
string
Can be repeated as key as often as needed for all indices. Example { "100.0": "1", "102.0": "teststring", }

Additional properties are allowed.
Examples
{ "Index.Subindex": "string" }

This example has been generated automatically.
SUB device/:ID/wrStatData
Used as response topic to putStatData The payload encodes success of writing the indices ## Result codes

0: OK - Parameter written

17: Key / index not available

18: Subindex not available

35: Access denied(key not writable or device is locked etc.)

48: Value out of range

49: Value greater than limit

50: Value less than limit

51: Value too long(size of data)

52: Value too short(size of data)

53: Function not available

54: Function temporarily not available

65: Parameter set inconsistent

998: Request timed out

999: General error / unknown cause
ID
required
integer
uid: ID
The ID of the device. More information about the device can be obtained via the Rest API
Accepts the following message:
wrStatData
object
uid: wrstatdata
object
value
string
result
integer
[ 0 .. 999 ]
Additional properties are allowed.
Additional properties are allowed.
Examples
{ "Index.Subindex": { "value": "string", "result": 999 } }

This example has been generated automatically.
SUB device/:ID/PDout
Processdata sent as input to the machine process

ID
required
integer
uid: ID
The ID of the device. More information about the device can be obtained via the Rest API
Accepts the following message:
processdata out
object
uid: pdinout
object
this key is repeated as often as values exist for observation

Unit
string
unit of the associated value. e.g. mm, C°, V, A

Value
integer
current value

Additional properties are allowed.
Additional properties are allowed.
Examples
{ ":MQTTLabel": { "Unit": "string", "Value": 0 } }

This example has been generated automatically.
SUB device/:ID/PDin
Processdata sent as result of the machine process

ID
required
integer
uid: ID
The ID of the device. More information about the device can be obtained via the Rest API
Accepts the following message:
processdata in
object
uid: pdinout
object
this key is repeated as often as values exist for observation

Unit
string
unit of the associated value. e.g. mm, C°, V, A

Value
integer
current value

Additional properties are allowed.
Additional properties are allowed.
Examples
{ ":MQTTLabel": { "Unit": "string", "Value": 0 } }

This example has been generated automatically.
SUB device/:ID/event
Events notify of changes in the machine state. e.g. warnings of wrong usage, production status change, configuration requiremenmts, productivity tips

ID
required
integer
uid: ID
The ID of the device. More information about the device can be obtained via the Rest API
Accepts the following message:
event
object
uid: event
code
integer
mode
string
Allowed values:
"APPEARS"
"DISAPPEARS"
"SINGLESHOT"
message
string
event name and remark combined

timestamp
string
format: datetime
timestampAPPEARS
string
format: datetime
DeltaCounter
deprecated
integer
ID
integer
id of the event in the database

type
string
Allowed values:
"Notification"
"Warning"
"Error"
"Unknown"
object
Name
string
Remark
string
Description
string
Cause
string
Impact
string
Solution
string
Additional properties are allowed.
Additional properties are allowed.
Examples
{ "code": 0, "mode": "APPEARS", "message": "string", "timestamp": "string", "timestampAPPEARS": "string", "DeltaCounter": 0, "ID": 0, "type": "Notification", "EventStrings": { "Name": "string", "Remark": "string", "Description": "string", "Cause": "string", "Impact": "string", "Solution": "string" } }

This example has been generated automatically.
SUB device/:ID/fwUpdateStatus
Notifies of status of a firmware update

ID
required
integer
uid: ID
The ID of the device. More information about the device can be obtained via the Rest API
Accepts the following message:
firmware update status
object
uid: fwupdate
Status
string
Allowed values:
"Fail"
"Ok"
"InProgress"
Message
string
Additional properties are allowed.
Examples
{ "Status": "Fail", "Message": "string" }

This example has been generated automatically.

SUB device/:ID/regDevice

complete device data on registration sent

Accepts the following message:

regDevice

object

uid: hardware

Examples

{
  "Active": "string",
  "allowDelete": true,
  "AllowFirmwareUpload": true,
  "AncestorMainDevID": 0,
  "ConnectionState": true,
  "Description": "string",
  "DeviceClassID": 0,
  "DeviceDescription": "string",
  "DeviceDescriptionAvailable": true,
  "DeviceDescriptionIconName": "string",
  "DeviceID": 0,
  "DeviceSubType": "string",
  "DeviceType": "string",
  "DocumentationNames": "string",
  "ExportCloud": true,
  "GuiDD_ID": 0,
  "Hidden": true,
  "IconFileName": "string",
  "ID": 0,
  "LocationID": 0,
  "ManuallyDeactivated": true,
  "MQTT_Protocol": "string",
  "Name": "string",
  "ParentDevID": 0,
  "PDbitLengthIn": true,
  "PDbitLengthObserve": true,
  "PDbitLengthOut": true,
  "PictureFileName": "string",
  "ProductID": "string",
  "ProductName": "string",
  "RegStatusID": 0,
  "SampleRate": "string",
  "SerialNumber": "string",
  "ShortName": "string",
  "Subinterface": "string",
  "UID": "string",
  "VendorID": 0
}

This example has been generated automatically.

SUB device/:ID/disDevice

complete device data on disconnect sent

Accepts the following message:

disDevice

object

uid: hardware

Examples

{
  "Active": "string",
  "allowDelete": true,
  "AllowFirmwareUpload": true,
  "AncestorMainDevID": 0,
  "ConnectionState": true,
  "Description": "string",
  "DeviceClassID": 0,
  "DeviceDescription": "string",
  "DeviceDescriptionAvailable": true,
  "DeviceDescriptionIconName": "string",
  "DeviceID": 0,
  "DeviceSubType": "string",
  "DeviceType": "string",
  "DocumentationNames": "string",
  "ExportCloud": true,
  "GuiDD_ID": 0,
  "Hidden": true,
  "IconFileName": "string",
  "ID": 0,
  "LocationID": 0,
  "ManuallyDeactivated": true,
  "MQTT_Protocol": "string",
  "Name": "string",
  "ParentDevID": 0,
  "PDbitLengthIn": true,
  "PDbitLengthObserve": true,
  "PDbitLengthOut": true,
  "PictureFileName": "string",
  "ProductID": "string",
  "ProductName": "string",
  "RegStatusID": 0,
  "SampleRate": "string",
  "SerialNumber": "string",
  "ShortName": "string",
  "Subinterface": "string",
  "UID": "string",
  "VendorID": 0
}

This example has been generated automatically.

SUB device/:ID/preregDevice

external triggered registration e.g. from plug or app

Accepts the following message:

preregDevice

object

uid: hardware

Examples

{
  "Active": "string",
  "allowDelete": true,
  "AllowFirmwareUpload": true,
  "AncestorMainDevID": 0,
  "ConnectionState": true,
  "Description": "string",
  "DeviceClassID": 0,
  "DeviceDescription": "string",
  "DeviceDescriptionAvailable": true,
  "DeviceDescriptionIconName": "string",
  "DeviceID": 0,
  "DeviceSubType": "string",
  "DeviceType": "string",
  "DocumentationNames": "string",
  "ExportCloud": true,
  "GuiDD_ID": 0,
  "Hidden": true,
  "IconFileName": "string",
  "ID": 0,
  "LocationID": 0,
  "ManuallyDeactivated": true,
  "MQTT_Protocol": "string",
  "Name": "string",
  "ParentDevID": 0,
  "PDbitLengthIn": true,
  "PDbitLengthObserve": true,
  "PDbitLengthOut": true,
  "PictureFileName": "string",
  "ProductID": "string",
  "ProductName": "string",
  "RegStatusID": 0,
  "SampleRate": "string",
  "SerialNumber": "string",
  "ShortName": "string",
  "Subinterface": "string",
  "UID": "string",
  "VendorID": 0
}

This example has been generated automatically.

SUB device/:ID/registration_status
Notifies of status of a device registration The RegStatusID encapsulates the new status of the device ## IDs

0: self preregistered

1: preregistered witout device description

2: device description provisioning in progress

3: parsing device description

4: preregistered with device description

5: registration in progress

6: registered

7: disconnected
ID
required
integer
uid: ID
The ID of the device. More information about the device can be obtained via the Rest API
Accepts the following message:
registration status
object
uid: registrationstatus
OldRegStatusID
integer
NewRegStatusID
integer
AncestorMainDevID
integer
>= 0
Additional properties are allowed.
Examples
{ "OldRegStatusID": 0, "NewRegStatusID": 0, "AncestorMainDevID": 0 }

This example has been generated automatically.
PUB device/:ID/removed
Device was removed from the network physically or manually via UI

ID
required
integer
uid: ID
The ID of the device. More information about the device can be obtained via the Rest API

Accepts the following message:
empty object
Examples

Schemas

object
uid: report
X_1
string
Primary cycle indicator

X_2
string
secondary cycle indicator, e.g. erasable or part cycle

X_3
string
secondary cycle indicator, e.g. erasable or part cycle

X_4
string
secondary cycle indicator, e.g. erasable or part cycle

Y_1
string
Y_2
string
Y_3
string
Y_4
string
Y_5
string
Y_6
string
Y_7
string
Y_8
string
Y_9
string
Y_10
string
Y_11
string
Y_12
string
Y_13
string
Y_14
string
Y_15
string
Y_16
string
Y_17
string
Y_18
string
Y_19
string
Y_20
string
Y_21
string
Y_22
string
Y_23
string
Y_24
string
Y_25
string
Y_26
string
Y_27
string
Y_28
string
Y_29
string
Y_30
string
Additional properties are allowed.
object
uid: observation
object
this key is repeated as often as values exist for observation

Unit
string
unit of the associated value. e.g. mm, C°, V, A

Value
string
current value

Additional properties are allowed.
Additional properties are allowed.
object
uid: pdinout
object
this key is repeated as often as values exist for observation

Unit
string
unit of the associated value. e.g. mm, C°, V, A

Value
integer
current value

Additional properties are allowed.
Additional properties are allowed.
object
uid: putstatdata
Index.Subindex
string
Can be repeated as key as often as needed for all indices. Example { "100.0": "1", "102.0": "teststring", }

Additional properties are allowed.
object
uid: wrstatdata
object
value
string
result
integer
[ 0 .. 999 ]
Additional properties are allowed.
Additional properties are allowed.
object
uid: fwupdate
Status
string
Allowed values:
"Fail"
"Ok"
"InProgress"
Message
string
Additional properties are allowed.
object
uid: registrationstatus
OldRegStatusID
integer
NewRegStatusID
integer
AncestorMainDevID
integer
>= 0
Additional properties are allowed.
object
uid: hardware
Active
string
allowDelete
boolean
AllowFirmwareUpload
boolean
AncestorMainDevID
integer
ConnectionState
boolean
Description
string
DeviceClassID
integer
DeviceDescription
string
DeviceDescriptionAvailable
boolean
DeviceDescriptionIconName
string
DeviceID
integer
DeviceSubType
string
DeviceType
string
DocumentationNames
string
ExportCloud
boolean
GuiDD_ID
integer
Hidden
boolean
IconFileName
string
ID
integer
LocationID
integer
ManuallyDeactivated
boolean
MQTT_Protocol
string
Name
string
ParentDevID
integer
PDbitLengthIn
boolean
PDbitLengthObserve
boolean
PDbitLengthOut
boolean
PictureFileName
string
ProductID
string
ProductName
string
RegStatusID
integer
SampleRate
string
SerialNumber
string
ShortName
string
Subinterface
string
UID
string
VendorID
integer
Additional properties are allowed.
object
uid: event
code
integer
mode
string
Allowed values:
"APPEARS"
"DISAPPEARS"
"SINGLESHOT"
message
string
event name and remark combined

timestamp
string
format: datetime
timestampAPPEARS
string
format: datetime
DeltaCounter
deprecated
integer
ID
integer
id of the event in the database

type
string
Allowed values:
"Notification"
"Warning"
"Error"
"Unknown"
object
Name
string
Remark
string
Description
string
Cause
string
Impact
string
Solution
string
Additional properties are allowed.
Additional properties are allowed.

How to connect:

Servers

Operations

SUB device/:ID/postReport

Examples

This example has been generated automatically.

PUB device/:ID/startObservation

Examples

SUB device/:ID/postObservation

Examples

This example has been generated automatically.

PUB device/:ID/putStatData

Examples

This example has been generated automatically.

SUB device/:ID/wrStatData

Examples

This example has been generated automatically.

SUB device/:ID/PDout

Examples

This example has been generated automatically.

SUB device/:ID/PDin

Examples

This example has been generated automatically.

SUB device/:ID/event

Examples

This example has been generated automatically.

SUB device/:ID/fwUpdateStatus

Examples

This example has been generated automatically.

SUB device/:ID/regDevice

Examples

This example has been generated automatically.

SUB device/:ID/disDevice

Examples

This example has been generated automatically.

SUB device/:ID/preregDevice

Examples

This example has been generated automatically.

SUB device/:ID/registration_status

Examples

This example has been generated automatically.

PUB device/:ID/removed

Examples

Schemas