JSON Integration 10222 d099 Jul19

JSON
Integration for
IO-Link
Draft 0.99
July 2019
Order No: 10.222

JSON Integration for IO-Link –2– Draft 0.99
File name: JSON_Integration_10222_d099_Jul19
This specification has been prepared by the IO-Link community.
Any comments, proposals, requests on this document are appreciated through the IO-Link CR
database www.io-link-projects.com. Please provide name and email address.
Login: IOL-JSON
Password: Report
Important notes:
NOTE 1 The IO-Link Community Rules shall be considered prior to the development and marketing of IO-Link
products. The document can be downloaded from the www.io-link.com portal.
Disclaimer:
The attention of adopters is directed to the possibility that compliance with or adoption of IO-Link Community
specifications may require use of an invention covered by patent rights. The IO-Link Community shall not be
responsible for identifying patents for which a license may be required by any IO-Link Community specification,
or for conducting legal inquiries into the legal validity or scope of those patents that are brought to its attention.
IO-Link Community specifications are prospective and advisory only. Prospective users are responsible for
protecting themselves against liability for infringement of patents.
The information contained in this document is subject to change without notice. The material in this document
details an IO-Link Community specification in accordance with the license and notices set forth on this page.
This document does not represent a commitment to implement any portion of this specification in any
company's products.
WHILE THE INFORMATION IN THIS PUBLICATION IS BELIEVED TO BE ACCURATE, THE IO-
LINK COMMUNITY MAKES NO WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, WITH REGARD TO
THIS MATERIAL INCLUDING, BUT NOT LIMITED TO ANY WARRANTY OF TITLE OR OWNERSHIP,
IMPLIED WARRANTY OF MERCHANTABILITY OR WARRANTY OF FITNESS FOR PARTICULAR PURPOSE
OR USE.
In no event shall the IO-Link Community be liable for errors contained herein or for indirect, incidental,
special, consequential, reliance or cover damages, including loss of profits, revenue, data or use, incurred
by any user or any third party. Compliance with this specification does not absolve manufacturers of IO-
Link equipment, from the requirements of safety and regulatory agencies (TÜV, BIA, UL, CSA, etc.).
® is a registered trademark. It may be used only by the members of the IO-Link

Community and non-members who had acquired the corresponding license. For more detailed
information on its use, refer to the rules of the IO-Link Community at www.io-link.com.
Publisher:
IO-Link Community
c/o PROFIBUS Nutzorganisation e.V.
Haid-und-Neu-Str. 7
76131 Karlsruhe
Germany
Phone: +49 721 / 96 58 590
Fax: +49 721 / 96 58 589
E-mail: info@io-link.com
Web site: www.io-link.com
© No part of this publication may be reproduced or utilized in any form or by any means, electronic or
mechanical, including photocopying and microfilm, without permission in writing from the publisher.
CONTENTS
1 Motivation and scope ....................................................................................................... 9

2 Normative references ...................................................................................................... 9
3 Terms, definitions, symbols, abbreviated terms and conventions ..................................... 9
3.1 Common terms and definitions ................................................................................ 9
3.2 Symbols and abbreviated terms ............................................................................ 10
3.3 Conventions .......................................................................................................... 10
3.3.1 Placeholders.................................................................................................. 10
3.3.2 Meaning of M/O/C.......................................................................................... 10
4 Architectural and technical scope .................................................................................. 10
4.1 General objectives ................................................................................................ 10
4.2 Security ................................................................................................................ 11
4.3 Device data and layer model ................................................................................. 11
4.4 General rules ........................................................................................................ 12
4.4.1 Master numbering .......................................................................................... 12
4.4.2 Port numbering .............................................................................................. 12
4.4.3 Device Naming .............................................................................................. 12
4.4.4 Access rights ................................................................................................. 12
4.4.5 Naming based on IODD ................................................................................. 12
4.4.6 Data Type conversion .................................................................................... 13
4.4.7 Byte Array conversion .................................................................................... 13
4.4.8 Time format ................................................................................................... 14
4.4.9 Error Behaviour ............................................................................................. 14
5 REST API ...................................................................................................................... 14
5.1 URL ...................................................................................................................... 14
5.2 HTTP Methods ...................................................................................................... 14
5.3 HTTP Requests / Responses ................................................................................ 15
5.4 Gateway ............................................................................................................... 15
5.4.1 GET /identification ......................................................................................... 16
5.4.2 GET /capabilities ........................................................................................... 16
5.4.3 GET /configuration ......................................................................................... 17
5.4.4 POST /configuration ...................................................................................... 18
5.4.5 POST /reset ................................................................................................... 19
5.4.6 POST /reboot ................................................................................................ 19
5.4.7 GET /events .................................................................................................. 20
5.5 Master .................................................................................................................. 22
5.5.1 GET / ............................................................................................................. 22
5.5.4 POST /identification ....................................................................................... 26
5.6 Port ...................................................................................................................... 26
5.6.1 GET / ............................................................................................................. 26
5.6.3 GET /status ................................................................................................... 28
5.6.4 GET /configuration ......................................................................................... 30
5.6.5 POST /configuration ...................................................................................... 31
5.6.6 GET /datastorage .......................................................................................... 32
5.6.7 POST /datastorage ........................................................................................ 33

5.7 Devices ................................................................................................................. 34
5.7.1 GET / ............................................................................................................. 34
5.7.4 POST /identification ....................................................................................... 38
5.7.5 GET /processdata/value ................................................................................ 39
5.7.6 POST /processdata/value .............................................................................. 43
5.7.7 GET /parameters ........................................................................................... 44
5.7.8 GET /parameters/{index}/subindices .............................................................. 45
5.7.9 GET /parameters/{parameterName}/subindices ............................................. 46
5.7.10 GET /parameters/{index}/value ...................................................................... 47
5.7.11 GET /parameters/{index}/subindices/{subindex}/value ................................... 48
5.7.12 GET /parameters/{parameterName}/value...................................................... 49
5.7.13 GET
/parameters/{parameterName}/subindices/{subParameterName}/value .......... 50
5.7.14 POST /parameters/{index}/value .................................................................... 51
5.7.15 POST /parameters/{parameterName}/value ................................................... 52
5.7.16 POST /parameters/{index}/subindices{subindex}/value .................................. 53
5.7.17 POST
/parameters/{parameterName}/subindices{subParameterName}/value ........... 53
5.7.18 POST /blockparametrization .......................................................................... 54
5.7.19 GET /events .................................................................................................. 58
5.8 IODD .................................................................................................................... 59
5.8.1 GET /iodds .................................................................................................... 59
5.8.2 POST /iodds .................................................................................................. 60
5.8.3 DELETE /iodds .............................................................................................. 60
5.8.4 GET /iodds .................................................................................................... 61
5.9 MQTT ................................................................................................................... 61
5.9.1 GET /mqtt/configuration ................................................................................. 62
5.9.2 POST /mqtt/configuration............................................................................... 63
5.9.3 GET /mqtt/topics ............................................................................................ 63
5.9.4 POST /mqtt/topics ......................................................................................... 65
5.9.5 DELETE /mqtt/topics/{topicID} ....................................................................... 66
5.9.6 GET /mqtt/topics/{topicId} .............................................................................. 66
6 MQTT topics format ....................................................................................................... 67
Annex A (normative) Status Codes and Errors on HTTP ...................................................... 69
A.1 HTTP Status Codes .............................................................................................. 69
A.2 JSON Errors ......................................................................................................... 69
Annex B (normative) JSON base objects ............................................................................. 71
B.1 General JSON objects .......................................................................................... 71
B.1.1 Cycle time object ........................................................................................... 71
B.1.2 Error object ................................................................................................... 71
B.1.3 Power Supply object ...................................................................................... 71
Bibliography .......................................................................................................................... 72
Figure 1 – Physical Master models ....................................................................................... 11

Figure 2 – Device layer model .............................................................................................. 11
Table 1 – IODD text conversion rules examples .................................................................... 13

Table 2 – Data type conversion ............................................................................................. 13
Table 3 – Mapping example of a bit sequence ...................................................................... 13
Table 4 – Base path .............................................................................................................. 14
Table 5 – HTTP Methods ...................................................................................................... 14
Table 6 – Resources overview .............................................................................................. 15
Table 7 – Resources Gateway .............................................................................................. 15
Table 8 – GET /identification ................................................................................................. 16
Table 9 – Object GatewayIdentification ................................................................................. 16
Table 10 – GET /capabilities ................................................................................................. 16
Table 11 – Object GatewayCapabilities ................................................................................. 17
Table 12 – GET /configuration .............................................................................................. 17
Table 13 – Object GatewayConfiguration .............................................................................. 17
Table 14 – Object MasterConfiguration ................................................................................. 18
Table 15 – POST /configuration ............................................................................................ 18
Table 16 – POST /reset ........................................................................................................ 19
Table 17 – POST /reboot ...................................................................................................... 19
Table 18 – GET /events ........................................................................................................ 20
Table 19 – Event log query parameters ................................................................................. 20
Table 20 – Object GatewayEventLog .................................................................................... 20
Table 21 – Object Origin ....................................................................................................... 21
Table 22 – Object Message .................................................................................................. 21
Table 23 – GET /masters ...................................................................................................... 22
Table 24 – Object MasterID .................................................................................................. 23
Table 25 – Resources Master ............................................................................................... 23
Table 27 – Object MasterCapabilities .................................................................................... 24
Table 28 – GET /identification ............................................................................................... 24
Table 29 – Object MasterIdentificationGet ............................................................................ 25
Table 30 – POST /identification ............................................................................................ 26
Table 31 – Object MasterIdentificationPost ........................................................................... 26
Table 32 – GET /{masterNumber}/ports ................................................................................ 26
Table 33 – Object Port ID ..................................................................................................... 27
Table 34 – Resources Port ................................................................................................... 27
Table 36 – Object PortCapability ........................................................................................... 28
Table 37 – GET /status ......................................................................................................... 28
Table 38 – Object PortStatus ................................................................................................ 29
Table 39 – port status mapping ............................................................................................. 29
Table 40 – GET /configuration .............................................................................................. 30
Table 41 – Object PortConfiguration .................................................................................... 30
Table 42 – POST /configuration ............................................................................................ 31
Table 43 – GET /datastorage ................................................................................................ 32

Table 44 – Object Datastorage ............................................................................................. 32
Table 45 – Object DataStorageHeader .................................................................................. 32
Table 46 – POST /datastorage .............................................................................................. 33
Table 47 – GET /devices ....................................................................................................... 34
Table 48 – Object DeviceName ............................................................................................. 34
Table 49 – Resources Devices.............................................................................................. 35
Table 51 – Object DeviceCapabilities .................................................................................... 36
Table 52 – GET /identification ............................................................................................... 37
Table 53 – Object Device Identification Get .......................................................................... 37
Table 54 – POST /identification ............................................................................................ 38
Table 55 – Object DeviceIdentificationPOST ......................................................................... 38
Table 56 – GET / processdata/value ..................................................................................... 39
Table 57 – format request query parameters ......................................................................... 39
Table 58 – process data content query parameters ............................................................... 40
Table 59 – Object ProcessDataInOut .................................................................................... 40
Table 60 – Object ProcessData ............................................................................................. 40
Table 61 – Object processDataIOL ....................................................................................... 40
Table 62 – POST /processdata/value .................................................................................... 43
Table 63 – GET /parameters ................................................................................................. 44
Table 64 – Object parameterList ........................................................................................... 44
Table 65 – GET /parameters/{index}/subindices .................................................................... 45
Table 66 – Object deviceSubParameters .............................................................................. 45
Table 67 – GET /parameters/{parameterName}/subindices ................................................... 46
Table 68 – GET /parameters/{index}/value ............................................................................ 47
Table 69 – deviceParameterValues object list ....................................................................... 47
Table 70 – Object complexParameterValue .......................................................................... 47
Table 71 – Object simpleParameterValue ............................................................................. 47
Table 72 – Object rawParameterValue .................................................................................. 48
Table 73 – GET /parameters/{index}/subindices/{subindex}/value ......................................... 49
Table 74 – GET /parameters/{parameterName}/value ........................................................... 49
Table 75 – GET /parameters/{parameterName}/subindices/{subParameterName}/value ........ 50
Table 76 – POST /parameters/{index}/value.......................................................................... 51
Table 77 – POST /parameters/{parameterName}/value ......................................................... 52
Table 78 – POST /parameters/{index}/subindices{subindex}value ......................................... 53
Table 79 – POST
/parameters/{ parameterName }/subindices{ subParameterName }value ............................... 53
Table 80 – POST /blockparametrization ................................................................................ 54
Table 81 – Object BlockparametrizationRequest ................................................................... 54
Table 82 – Object BlockparametrizationReadResponse ........................................................ 55
Table 83 – Object ParameterAddress.................................................................................... 55
Table 84 – Object ParameterValue ....................................................................................... 55
Table 85 – Object IndexAddress ........................................................................................... 55

Table 86 – Object SubIndexAddress ..................................................................................... 56
Table 87 – GET /events ........................................................................................................ 58
Table 88 – DeviceEvent log query parameters ...................................................................... 58
Table 89 – Resources for IODDs .......................................................................................... 59
Table 90 – GET /iodds .......................................................................................................... 59
Table 91 – Object IODDIdentification .................................................................................... 59
Table 92 – POST /iodds ........................................................................................................ 60
Table 93 – DELETE /iodds .................................................................................................... 60
Table 94 – GET /iodds .......................................................................................................... 61
Table 95 – Resources MQTT configuration ........................................................................... 61
Table 96 – GET /mqtt/configuration....................................................................................... 62
Table 97 – Object MQTTConfiguration .................................................................................. 62
Table 98 – Object LastWill .................................................................................................... 62
Table 99 – POST /mqtt/configuration .................................................................................... 63
Table 100 – GET /mqtt/topics ............................................................................................... 64
Table 101 – Object MQTTtopic ............................................................................................. 64
Table 102 – Object MQTT ProcessDataTopic........................................................................ 64
Table 103 – POST /mqtt/topics ............................................................................................. 65
Table 104 – DELETE /mqtt ................................................................................................... 66
Table 105 – GET /mqtt/topics ............................................................................................... 66
Table 106 – HTTP Status codes ........................................................................................... 69
Table 107 – JSON Error codes ............................................................................................. 69
Table 108 – Object CycleTime .............................................................................................. 71
Table 109 – Object Error ....................................................................................................... 71
Table 110 – Object PowerSupply .......................................................................................... 71
1 0 Introduction
2 0.1 General
3 The base technology of IO-Link TM 1 is subject matter of the international standard IEC 61131-
4 9 (www.iec.ch). IEC 61131-9 is part of a series of standards on programmable controllers and
5 the associated peripherals and should be read in conjunction with other parts of the series.
7 0.2 Patent declaration

8 The IO-Link Community draws attention to the fact that it is claimed that compliance with this
9 document may involve the use of patents concerning the point-to-point serial communication
10 interface for small sensors and actuators as follows, where the [xx] notation indicates the
11 holder of the patent right:
Patent number [xx] Title
12 IO-Link Community takes no position concerning the evidence, validity and scope of these
13 patent rights.
14 The holders of these patents rights have assured the IO-Link Community that they are willing
15 to negotiate licences either free of charge or under reasonable and non-discriminatory terms
16 and conditions with applicants throughout the world. In this respect, the statements of the
17 holders of these patent rights are registered with the IO-Link Community.
18 Information may be obtained from:
[xx] Name and address of patent holder
19
20 Attention is drawn to the possibility that some of the elements of this document may be the
21 subject of patent rights other than those identified above. The IO-Link Community shall not be
22 held responsible for identifying any or all such patent rights.
23 The IO-Link Community maintains on-line data bases of patents relevant to their standards.
24 Users are encouraged to consult the databases for the most up to date information
25 concerning patents.
26
1 IO-Link TM is a trade name of the "IO-Link Community". This information is given for the convenience of users of
this specification and does not constitute an endorsement by the "IO-Link Community" of the trade name holder
or any of its products. Compliance to this standard does not require use of the registered logos for IO-LinkTM.
Use of the registered logos for IO-Link TM requires permission of the "IO-Link Community".
27 IO-Link JSON Mapping

28 1 Motivation and scope
29 New use cases and requirements concerning the integration between modern IT systems and
30 the production floor require new device interfaces. The connections today mainly focus on the
31 integration of a device into fieldbuses and PLC systems. Cyclic data exchange and real time
32 are the most important requirements for today field bus implementations. The techniques
33 used are completely different than the ones used for the rest of the IT world. On the other
34 hand, modern automation devices provide a way to communicate over TCP/IP networks
35 beside the real time communication with the PLC over the field bus.
36 This document describes a device data model, objects and semantics for mapping on IT
37 relevant connections or services.
38 This document describes a REST API
39 a) for data access to IO-Link masters, ports and devices and the gateway.
40 b) for IODD file management (up/download).
41 c) for MQTT client configuration.
42
43 2 Normative references
44 The following documents, in whole or in part, are normatively referenced in this document and
45 are indispensable for its application. For dated references, only the edition cited applies. For
46 undated references, the latest edition of the referenced document (including any
47 amendments) applies.
48 IO-Link Community, IO-Link System Description – Technology and Application, Version

49 February 2016, Order No. 4.392 (available at http://www.io-link.com)
50 IO-Link Community, IO-Link Interface and System Specification, Version 1.1.3, Order No.
51 10.002 (available at http://www.io-link.com)
52 IO-Link Community, IO Device Description (IODD), Version 1.1, Order No. 10.012
53
54 3 Terms, definitions, symbols, abbreviated terms and conventions

55 3.1 Common terms and definitions
56 For the purposes of this document, the terms and definitions given in IEC 61131-1 and IEC
57 61131-2, as well as the following apply.
58 Master
59 Active peer connected through ports to one up to n devices providing an interface to the
60 gateway to the upper level communication systems (e.g. PLCs or edge gateways)
61 Note: Uppercase "Master" is used for SDCI equipment, while lowercase "master" is used in a generic manner.
62 Port
63 Communication interface of the Master to one Device
64 IODD
65 The XML based IO Device Description of an IO-Link device see [2].
66 PIN 2
67 The physical digital I/O interface of an IO-Link port usually used with M12 and M8 connectors
JSON Integration for IO-Link – 10 – Draft 0.99
68 PIN 4
69 The physical digital I/O interface of an IO-Link port usually used with M12 and M8 connectors
70 IO-Link communication runs physically over PIN 4 and is called C/Q.
71 SIO
72 Standard Input Output mode. This could be a digital input or a digital output.
73 masterNumber
74 This is the number of a specific master within the gateway
75 portNumber
76 This is the number of a specific port within the Master
77 URL
78 This is an Uniform Resource Locator
79
80 3.2 Symbols and abbreviated terms

C/Q connection for communication (C) or switching (Q) signal (SIO)
DI digital input (data coming from a Device to a Master)
DO digital output (data going from a Master to a Device)
M/O/C Mandatory, optional, conditional see 3.3.2
81 3.3 Conventions
82 3.3.1 Placeholders
83 Strings that are embraced by {} are placeholders for variables.
84 Note: This convention is not applicable for JSON objects.
85
86 3.3.2 Meaning of M/O/C

87 It is mandatory to implement the handling of objects and key value pairs that are marked with
88 “M”.When sending a HTTP Post request a client is not obligated to provide all objects or key
89 value pairs. The resource has to be updated by merging the newly received data with the
90 existing data.
91
92 4 Architectural and technical scope

93 4.1 General objectives
94 As summarized in the IO-Link System Description, an IO-Link system consists of an IO-Link
95 master, IO-Link devices and cables connecting the IO-Link devices to the IO-Link Master
96 A physical IO-Link Gateway consists of one or more Masters containing one or more ports. On
97 each port an IO-Link device may be connected. The physical IO-Link Gateway may also have
98 one or more Gateway applications (e.g. Webserver, OPC UA server or MQTT client).
99
100 Figure 1 – Physical Master models
101
102
103 4.2 Security

104 For data security it is recommended to use TLS-PSK with AES for the transport layer security.
105
106 4.3 Device data and layer model

107 This device layer model (including gateway, IO-Link master and devices) is used to structure
108 the REST API described in this specification.
109
110
111 Figure 2 – Device layer model
112
113 This layer model comprises compact modules containing one Master as well as modular
114 devices with N Masters.
115
116 4.4 General rules

117
118 4.4.1 Master numbering

119 Addressing of IO-Link masters within a gateway starts with number 1 for the first master.
120 4.4.2 Port numbering

121 Addressing of IO-Link ports within a master starts with number 1 for the first port.
122 4.4.3 Device Naming

123 Devices are accessed by names. Following rules for the device naming apply:
124 1. The default device name is created based on Master number and Port number in the
125 format master{masterNumber}port{portNumber}.
126 2. The default device name can be changed via port configuration (see 5.6.5.).
127 3. The definition of duplicated device names has to be rejected.
128 4. A device name must only contain alphanumeric characters and underscores.
129 5. A device names maximum length is 32 characters minimum length is 1 character.
130 Examples:
”master2port4” is the default name of an device connected to port 4 of master 2

”exampleSensor” this is a new assigned name to a device
131
132 4.4.4 Access rights

133 All requests for writing data may be blocked due to right restrictions. Also resetting or
134 rebooting may be not allowed due to right restrictions. Requests for writing data without
135 having permission to do so, will respond with an error. The data will remain unchanged.
136 It is recommended to use access restrictions to handle the access of multiple clients to the
137 same resource.
138 4.4.5 Naming based on IODD

139 It is optionally also possible to access IO-Link data (comprizing IO-Link process data and IO-
140 Link parameters) by name rather than by index and subindex.
141 Constraints for strings in keys of JSON key-value-pairs (see [3]) and URLs require the
142 following conversion rules for those names:
143 Rule 1: Names are based on the IODD XML Element Name inside variables or process data
144 resolving the text in primary language
145 Rule 2: Special characters get replaced by „_“
146 Rule 3: Leading numbers shall be prefixed with „_“
147 Rule 4: If there are duplicated IO-Link names, the IO-Link index or subindex has to be
148 accessed by appending the index number or subindex number behind the name according to
149 the following scheme: {name}_{index} or {name}_{subindex}.
150 Rule 5: Naming according the scheme {name}_{index} or {name}_{subindex} is always

151 allowed even if names are not duplicated.
152
153 Examples:
154 Table 1 – IODD text conversion rules examples
IODD text Name ISDU Unique name (Name_Index)

Index/subindex
0815 variable _0815_variable 3452 _0815_variable_3452

Switchpoint (Q1) Switchpoint__Q1_ 345 Switchpoint__Q1_345
1)
External temperature External_temperature 311 External_temperature_311
1)
External temperature External_temperature 1423 External_temperature_1423
Note 1) this is a naming conflict (duplicate)
155
156 4.4.6 Data Type conversion

157 The following conversion rules in Table 2 apply for the data type mapping between IO-Link
158 and JSON.
159 Table 2 – Data type conversion
IO-Link data type JSON data type
BooleanT Boolean
StringT String
ArrayT Array
OctetStringT see Byte Array Conversion 4.4.7
IntegerT, UintegerT Number
Float32T Number
RecordT Object
TimeSpanT String
TimeT String
160
161 4.4.7 Byte Array conversion

162 This is the description how to map byte arrays to JSON.
163 Bit sequences that are not interpretable without using information out of the IODD are
164 represented as JSON arrays of decimal numbers. One array item is representing one byte. If
165 the value of the bit sequence is not a multiple of 8, the value is padded with zeros from the
166 left until to the next byte border. Byte order is big-endian, see [1].
167 Example:
168 Table 3 – Mapping example of a bit sequence
value (bin) bit length value (hex) Byte Array (dec)
10 0111 6 0x27 [39]
100 0000 15 0x40F0 [64, 240]

1111 0000
169
170
171 4.4.8 Time format

172 Any time values shall be represented either as an absolute time or a relative time in the
173 format as specified in ISO 8601 (see [4])
174 Note: The italic letters in the following format definitions are to be replaced by one digit. The square brackets
175 indicate that an element is optional.
176 The format for absolute time is JJJJ-MM-TTThh:mm:ss.fZ
177 Time format for relative time is P[JY][MM][WW][TD][T[hH][mM][s[.f]S]]
178 Examples:
Absolute time: 2018-05-18T07:31:54.123Z

Relative time: P3Y6M4DT12H30M17.123S
179
180 4.4.9 Error Behaviour

181 While processing HTTP request errors may occur. There are several errors defined (see
182 appendix A.2). The body of an HTTP response indicating an error contains the Error Object as
183 defined in B.1.2.
184 Following general rules apply for the error handling:
185 a) Errors 101 and 150 (see appendix A.2) can be returned to each request.
186 b) If parts of POST requests are not applicable, the HTTP response has a different HTTP
187 status code that 2xx. The body of this HTTP response shall contain the Error Object
188 as defined in B.1.2.
189 c) If multiple errors occur while processing the request only the first detected error shall
190 be responded.
191 d) Errors 305 and 306 (see A.2) can be returned to requests when there are query
192 parameters added to the URL.
193 e) If REST API commands are not available, error 103 (see A.2) shall be responded.
194
195 5 REST API

196 5.1 URL
197 The base path for this version is listed in Table 4
198 Table 4 – Base path
Base path Remark M/O/C
/iolink/v1 Example: “/iolink/v1/masters/1/ports/2/status” M
199
200 5.2 HTTP Methods

201 The following HTTP methods shall be used
202 Table 5 – HTTP Methods

203
HTTP Methods description M/O/C
GET Request data from the server M

POST Transmit data to the server M

DELETE Delete resources on the server M
OPTIONS List supported HTTP methods of the server O
204
205 5.3 HTTP Requests / Responses

206 The URLs are build out of a base URL which is followed by a subsequent path. Query strings
207 are added optionally.
208 The HTTP request headers Content-type and Accept are set to application/json by
209 default.
210
211
212 Table 6 – Resources overview

213
Resource clause remark M/O/C
/gateway 5.4 Address the Gateway M

/masters 5.5 Get all available masterNumber keys and M
identification information
/masters/{masterNumber} 5.5 Address one specific master M
/masters/{masterNumber} 5.6.1 Get all available portNumber keys M
/ports
/masters/{masterNumber} 5.6.1 Addressing one specific port of a specific master M
/ports
/{portNumber}
/devices 5.7 Addressing all devices of all masters M
/devices/{deviceName} 5.7.3 Addressing specific devices by name M
/mqtt 5.9 Configuration of MQTT clients C 2)
/iodds 5.8 IODD file handling C 1)
Note 1) this resource is mandatory if the IODD feature is supported
Note 2) this resource is mandatory if the MQTT feature is supported
214
215 Examples:
HTTP://192.168.178.22/iolink/v1/gateway
HTTP://192.168.178.22/iolink/v1/masters/1
HTTP://192.168.178.22/iolink/v1/masters/2/ports/7
HTTP://192.168.178.22/iolink/v1/devices/sensor34
216 5.4 Gateway

217 Table 7 – Resources Gateway
218
Resources clause HTTP description M/O/C
/iolink/v1/gateway Method
/identification 5.4.1 GET Read the indentification of the REST API Gateway M
/capabilities 5.4.2 GET Read the capabilities of the gateway M
/configuration 5.4.3 GET Read the network configuration of the gateway M
/configuration 5.4.4 POST Write the network configuration of the gateway M
/reset 5.4.5 POST Reset the gateway including all masters O
/reboot 5.4.6 POST Reboot the gateway including all masters O
/events 5.4.7 GET Read the EventLog containing all events from M
gateway, masters, ports and devices.
219
220 5.4.1 GET /identification

221 Read the indentification of the REST API Gateway.
222
223 Table 8 – GET /identification

224
Description
Description Read the indentification of the REST API Gateway

System Behaviour Nothing will be changed or modified
Path parameters –
Query parameters –
Errors 301 (see A.2), see 4.4.9
Success 200 OK
Request body –
Response body Object Gateway Identification see Table 9
225
226 Table 9 – Object GatewayIdentification
227
object GatewayIdentification
property type value description M/O/C
macAddress string e.g. "00:02:72:CE:A6:49" MAC address 6 bytes M
228
229 Example :
230 Request
GET /iolink/v1/gateway/identification
231 Response
{
"macAddress": "00:02:72:CE:A6:49"
}
232
233 5.4.2 GET /capabilities

234 Read the capabilities of the IO-Link gateway.
235
236 Table 10 – GET /capabilities

237
Description
Description Read the capabilities of the IO-Link gateway

Path parameters –
Success 200 OK
Request body –
Response body object defined in Table 11 – Object GatewayCapabilities
238
239 Table 11 – Object GatewayCapabilities
240
object GatewayCapabilities

ioddSupported boolean true, false true if the IODD feature is supported M
mqttSupported boolean true, false true if the MQTT feature is supported M
241
242 Example:
243 Request
GET /iolink/v1/gateway/capabilities
244 Response
{
"ioddSupported": true,
"mqttSupported": false
}
245
246 5.4.3 GET /configuration

247 Read the actual acting configuration of the IO-Link gateway.
248 Table 12 – GET /configuration

249
Description
Description Read the actual acting configuration of the IO-Link gateway. The gateway may support
multiple IPv4 interfaces.
Path parameters –
Success 200 OK
Request body –
Response body object defined in Table 13 – Object GatewayConfiguration
250
251
252 Table 13 – Object GatewayConfiguration
253
Object GatewayConfiguration
property type Value description M/O/C
ethIpv4 Array of Objects defined in Table 14 – Object M

object MasterConfiguration
254
255 Table 14 – Object MasterConfiguration

256
Object MasterConfiguration
ipAddress string e.g. 192.168.1.13 M
subnetMask string e.g. 255.255.255.0 M
standardGateway string e.g. 192.168.1.1 M
257
258 Example:
259 Request
GET /iolink/v1/gateway/configuration
260 Response
{
"ethIpv4": [
{
"ipAddress": "192.168.1.13",
"subnetMask": "255.255.255.0",
"standardGateway": "192.168.1.1"
}
]
}
261
262 5.4.4 POST /configuration

263 Write configuration data to the gateway.
264 Table 15 – POST /configuration

265
Description
Description Write configuration data to the gateway.

System Behaviour If there are no restrictions the values of the object will be modified.
The response shall be send prior to the change of the IP configuration.
Path parameters –
Errors 201, 202, 203, 204, 205, 206 (see A.2), see 4.4.9
Success 204 No Content
Request body object defined in Table 13 – Object GatewayConfiguration
Response body –
266
267 Example:
268 Request (changing an IPv4 interface)
POST /iolink/v1/gateway/configuration
{
"ethIpv4": [
{
"ipAddress": "192.168.1.13",
"subnetMask": "255.255.255.0",
"standardGateway": "192.168.1.1"
}
]
}
269
270 5.4.5 POST /reset

271 This invokes a reset of the IO-Link Gateway. This may reset all configuration data and
272 interrupt all communications channels. It is recommended to log this within the EventLog (see
273 5.4.7).
274
275 Table 16 – POST /reset

276
Description
Description This invokes a reset of the IO-Link Gateway

System Behaviour If there are no restrictions the response will be given and following the gateway will be
reset
Path parameters –
Errors (see A.2), see 4.4.9
Request body –
Response body –
277
278 Example:
279 Request
POST /iolink/v1/gateway/reset
280
281 5.4.6 POST /reboot

282 This invokes a reboot of the IO-Link Gateway. This may reset all configuration data and
283 interrupt all communications channels. It is recommended to log this within the EventLog (see
284 5.4.7).
285 Table 17 – POST /reboot

286
Description
Description This invokes rebooting of the IO-Link Gateway

System Behaviour If there are no restrictions the response will be given and following the gateway will be
reset
Path parameters –
Request body –
Response body –
287
288 Example:
289 Request
POST /iolink/v1/gateway/reboot
290
291 5.4.7 GET /events

292 Each gateway shall have an Event Log object containing the events of devices, ports and the
293 masters. The content of the Event Log can be read by getting the object “Gateway Event Log”
294 (see Table 20 ).
295 Table 18 – GET /events

296
Description
Description Reading the Event Log. A filtered subset of the Event log object is achieved by adding
query parameters to the URL. If there are no events to respond the “Gateway Event Log”
objects is empty.
System Behaviour Nothing will be changed or modified.
Path parameters –
Query parameters Event log query parameters (see Table 19)
Errors (see A.2) , see 4.4.9
Success 200 OK
Request body –
Response body object defined in Table 20 – Object GatewayEventLog
297
298 Table 19 – Event log query parameters

299
query parameter values Remark
origin ALL, GATEWAY,MASTERS, Default is ALL

PORTS, DEVICES
masterNumber {masterNumber} masterNumber is only applicable with origin=MASTERS
and with origin=PORTS
portNumber {portNumber} portNumber is only applicable with origin=PORTS
deviceName {deviceName} deviceName is only applicable with origin=DEVICES
top 1…n Delivers the oldest n events of the event buffer.
top is mutually exclusive to bottom.
bottom 1…m Delivers the latest n events of the event buffer.
bottom is mutually exclusive to top.
300
301 Table 20 – Object GatewayEventLog

302
object Gateway EventLog
property Type value description M/O/C
time string Relative or absolute time as defined in 4.4.8 When the event was logged M
severity string Enumeration: Reference is Syslog Protocol M

“EMERGENCY” RFC5424 see [5]
“ALERT” Indicates the severity of the
message. The severity is
“CRITICAL” decreasing from EMERGENCY to
“ERROR” DEBUG.
“WARNING” IO-Link EventTypes mapping is:
“NOTICE” "NOTIFICATION" maps to

“INFO” "NOTICE",
"WARNING" to "WARNING" and
“DEBUG” "ERROR" to "ERROR".
origin object object defined in Table 21 – Object Origin M
message object object defined in Table 22 – Object Message M
303
304 Table 21 – Object Origin

305
object
gateway string vendor-specific String This is for vendor specific C1

origins e.g. Web server
application or MQTT, etc.
masterNumber number masterNumber C2
portNumber number portNumber C3
deviceName string deviceName C4
Note 1) Origin gateway has to be used if the event comes from the gateway.
Note 2) Origin masterNumber has to be used if the event comes from master, port or device.
Note 3) Origin portNumber has to be used if the event comes from port or device.
Note 4) Origin deviceName has to be used if the event comes from the device.
306
307 Table 22 – Object Message

308
object Message
code number codes according in [1] Annex D shall be used if the origin is C1
device or port
mode string codes according in [1] 8.2.2.11 shall be used if the origin is SINGLE_SHOT C1
device or port APPEARS
DISAPPEARS
text string Message. (For IO-Link event code related messages (defined C1
in [1] ) shall be used)
Note 1) At least one of the properties has to be used.

309
310 Examples:
311 Reading all events of the gateway
312 Request
GET /iolink/v1/gateway/events
313 Response
[
{
"time": "2018-05-18T07:31:54.123Z",
"severity": "WARNING",
"origin": {
"masterNumber": 1,
"portNumber": 1,
"deviceName": "Temp_sensor_1"
},
"message": {
"code": 16912,
"mode": "APPEARED",
"text": "Device temperature over-run – Clear source of heat"
}
},
{
"time": "2018-05-18T07:35:54.123Z",
"severity": "NOTIFICATION",
"origin": {
"masterNumber": 1,
"portNumber": 2
},
"message": {
"code": 65314,
"mode": "SINGLESHOT",
"text": "Device communication lost"
}
}
]
314
315 Request reading the oldest 3 events of port 7 of master 2
GET /iolink/v1/gateway/events?origin=PORTS&top=3&portNumber=7
316
317 Request reading all events of master 3
GET /iolink/v1/gateway/events?origin=MASTERS&masterNumber=3
318
319 5.5 Master

320 There can be more than 1 master addressed by one gateway. Typical multi master
321 applications are modular devices. Masters within a gateway are addressed by
322 “masterNumber” which starts at 1 for the first master.
323 Example:
HTTP://192.168.178.22/iolink/v1/masters/1
324
325 5.5.1 GET /

326 This is for scanning all masters within a Gateway.
327
328 Table 23 – GET /masters

329
Description
Description read all the available masterNumber keys with the corresponding identification
information
Path parameters –
Success 200 OK
Request body -
Response body Array of object defined in Table 24 – Object MasterID
330
331 Table 24 – Object MasterID

332
object MasterID
masterNumber number Integer 1..n M
serialNumber string Vendor specific O
locationTag string Could be used for “slot” information for the O

modular model (see 4.1)
333
334 Example:
335 Request
HTTP://192.168.178.22/iolink/v1/masters
336 Response
[
{
"masterNumber": 1,
"serialNumber": "lsdfkjke93922",
"locationTag": "slot 5"
},
{
"masterNumber": 2,
"serialNumber": "dsadasda25632",
"locationTag": "slot 6"
}
]
337
338
339 Table 25 – Resources Master

340
Resources clause HTTP remark M/O/C
/iolink/v1/masters/ Method
{masterNumber}
/capabilities 5.5.2 GET Read the capabilities of the master M

/identification 5.5.3 GET Read the identification of the IO-Link master M
/identification 5.5.4 POST Write application specific identification to a master M
341

343 This is for reading the capabilities of an IO-Link master.

345
Description
Description Read the capabilities of the IO-Link master

Path parameters –
Success 200 OK
Request body –
Response body Object Master Capability (see Table 27 – Object MasterCapabilities
346
347 Table 27 – Object MasterCapabilities
348
Object MasterCapabilities
property type values description M/O/C

numberOfPorts number Integer 1..n Total number of ports M
maxPowerSupply object object defined in Table 110 – Maximum total power supply M
Object PowerSupply for all ports.
349
350 Example:
351 Request
GET /iolink/v1/masters/1/capabilities
352 Response
{
"numberOfPorts": 8,
"maxPowerSupply": {
"value": 0.3,
"unit": "A"
}
}
353

355 This is for reading identification data of an IO-Link master

357
Description
Description Read all identification data of an IO-Link master

Path parameters –
Success 200 OK
Request body –
Response body object defined in Table 29 – Object MasterIdentificationGet
358
359
360 Table 29 – Object MasterIdentificationGet

361
object MasterIdentificationGet
vendorId integer Vendor ID assigned by IO- M

Link community, see [1]
masterID integer Any vendor specific ID O
masterType string Enumeration: see [1] M

“Unspecific”
“Master acc. V1.0”
“Master acc. V1.1”
“Failsafe_Master”
“Wireless_Master”
serialNumber string Vendor specific, see [1] O
orderCode string Vendor specific, see [1] M
vendorName string Vendor specific, see [1] M
hardwareRevision string Vendor specific, see [1] O
softwareRevision string Vendor specific, see [1] O
website string Link to product site O
manual string Link to user manual O
applicationSpecificTag string User defined tag, see [1] O
locationTag string User defined tag, see [1] O
functionTag string User defined tag, see [1] O
362
363 Example:
364 Request
GET /iolink/v1/masters/1/identification
365 Response
{
"vendorName": "SICK AG",
"vendorId": 26,
"masterId": 42,
"masterType": "Master acc. V1.0",
"serialNumber": "IOLM123456",
"orderCode": "PROD-123456",
"productName": "IO-Link Master",
"hardwareRevision": "3.2.1.444R",
"softwareRevision": "3.2.1.888R",
"website": "http://www.sick.de/io-link-master",
"manual": "http://www.sick.de/io-link-master/documentation.pdf",
"applicationSpecificTag": "Fallback reader at the end of the belt",
"locationTag": "Down under",
"functionTag": "Code reading"
}
366
367 5.5.4 POST /identification

368 This is for setting the identification data of an IO-Link master.
369 Table 30 – POST /identification

370
Description
Description write all identification data of an IO-Link master

System Behaviour if there are no restrictions the object will be modified
Path parameters –
Request body object defined in Table 31 – Object MasterIdentificationPost
Response body -
371
372 Table 31 – Object MasterIdentificationPost

373
object MasterIdentificationPost

applicationSpecificTag string User defined tag, see [1] O
locationTag string User defined tag, see [1] O
functionTag string User defined tag, see [1] O
374
375 Example
376 Request
POST /iolink/v1/masters/1/identification
{
"applicationSpecificTag": "Fallback reader at the end of the belt",
"functionTag": "Code reading"
}
377
378 5.6 Port

379
380 5.6.1 GET /

381 Get all the available portId keys of one specific master.
382 Table 32 – GET /{masterNumber}/ports

383
Description
Description read all the available portNumber keys with the corresponding identification information
Path parameters –
Success 200 OK
Request body -
Response body array of object defined in Table 33 – Object Port ID
384
385 Table 33 – Object Port ID

386
object Port IDs

portNumber number Integer 1..n M
387
388 Example:
389 Request
HTTP://192.168.178.22/iolink/v1/masters/1/ports
390 Response
[
{
"portNumber": 1
},
{
"portNumber": 2
},
{
"portnumber": 3
},
{
"portnumber": 4
}
]
391
392
393 Table 34 – Resources Port

394
masters/{masterNumber}/ Method
ports/{portNumber}
/capabilities 5.6.2 GET Read the capability information of the M

specified port
/status 5.6.3 GET Read the actual status of the selected port M
/configuration 5.6.4 GET Read the actual configuration of the specified M
port
/configuration 5.6.5 POST Write the configuration of the specified port M
/datastorage 5.6.6 GET Read the datastorage content of a specific M
port
/datastorage 5.6.7 POST Write the datastorage content to a specific M
port
395
397 Reads the capabilities of a specific port.

399
Description
Description Reads the capabilities of a specific port

Path parameters –
Errors 302, 303 (see A.2), see 4.4.9
Success 200 OK
Request body –
Response body object defined in Table 36 – Object PortCapability
400
401
402 Table 36 – Object PortCapability

403
object Port capability
property type value remark M/O/C
portType string Enumeration: see [1], M

“CLASS_A” SMI
“CLASS_B”
“CLASS_A_WITH_PORT_POWER_OFF_ON”
“FAILSAFE_PORT_A_WITHOUT_SAFETY_DIGITAL_INPUTS”
“FAILSAFE_PORT_A_WITH_ SAFETY_DIGITAL_INPUTS”
“FAILSAFE_PORT_B”
“WIRELESS_MASTER”
maxPowerSupply object object defined in Table 110 – Object PowerSupply M
404
405 Example:
406 Request
HTTP://192.168.178.22/iolink/v1/masters/1/ports/1/capability
407 Response
{
"maxPowerSupply": {
"value": 0.3,
"unit": "A"
},
"portType": "CLASS_A"
}
408
409
410 5.6.3 GET /status

411 Reads the actual status of a specific port.
412 Table 37 – GET /status

413
Description
Description Reads the actual status of a specific port


Path parameters –
Errors 302, 303 (see A.2), see 4.4.9
Success 200 OK
Request body –
Response body object defined in Table 38 – Object PortStatus
414
415 Table 38 – Object PortStatus

416
object Port Status

statusInfo string Enumeration: see Table 39 – port M
“DEACTIVATED” status mapping
“INCORRECT_DEVICE”
“DEVICE_STARTING”
“DEVICE_ONLINE”
“COMMUNICATION_LOST”
“DI_C/Q DIGITAL_INPUT_PIN4”
“DO_C/Q DIGITAL_OUTPUT_PIN4”
“NOT_AVAILABLE”
ioLinkRevision string Enumeration: C1
“1.0”
“1.1”
transmissionRat string Enumeration: C1
e “COM1”
“COM2”
“COM3”
masterCycleTime object Object defined in Table 108 – Object C2
CycleTime
Note 1) only applicable if port is in status “DEVICE_ONLINE” or “DEVICE_STARTING”
Note 2) only applicable if port is in status “DEVICE_ONLINE”
417
418 Table 39 – port status mapping

419
JSON SMI
DEACTIVATED DEACTIVATED, PORT_POWER_OFF
INCORRECT_DEVICE PORT_DIAG
DEVICE_STARTING PREOPERATE
DEVICE_ONLINE OPERATE
COMMUNICATION_LOST NO_DEVICE
DI_C/Q DIGITAL_INPUT_PIN4 DI_C/Q
DO_C/Q DIGITAL_OUTPUT_PIN4 DO_C/Q
NOT_AVAILABLE NOT_AVAILABLE
420
421
422
423 Example:
424 Request
HTTP://192.168.178.22/iolink/v1/masters/1/ports/1/status
425 Response
{
"portStatusInfo": "DEVICE_ONLINE",
"ioLinkRevision": "1.1",
"transmissionRate": "COM2",
"masterCycleTime": {
"value": 2.3,
"unit": "ms"
}
}
426
427 5.6.4 GET /configuration

428 Reads the actual configuration of a specific port
429 Table 40 – GET /configuration

430
Description
Description Read the actual configuration of a specific port

Path parameters –
Errors 302, 303 (see A.2), see 4.4.9
Success 200 OK
Request body –
Response body object defined in Table 41 – Object PortConfiguration
431
432 Table 41 – Object PortConfiguration
433
object Port configuration
property type values description M/O/C
mode string Enumeration: see [1], Table E3 M

“DEACTIVATED”
“IOLINK_MANUAL”
“IOLINK_AUTOSTART”
“DIGITAL_INPUT”
“DIGITAL_OUTPUT”
validationAndBackup string Enumeration: see [1], Table E3 M
“NO_DEVICE_CHECK”
“TYPE_COMPATIBLE_DEVICE_V1.0” only available if
“TYPE_COMPATIBLE_DEVICE_V1.1” ports is in mode
IOLINK MANUAL
“TYPE_COMPATIBLE_DEVICE_V1.1_BA
CKUP_AND_RESTORE”
“TYPE_COMPATIBLE_DEVICE_V1.1_RE
STORE”
pin2Configuration string Enumeration: M/C 2
“NOT_SUPPORTED”
“DIGITAL_INPUT”
“DIGITAL_OUTPUT”
4
cycleTime object Object defined in Table 108 – Object Note
CycleTime
vendorId number see [1] C1
deviceId number see [1] C1
deviceName String Default Name is: M/O 3

Maste{masterNumer}port{portNumber}
Note 1) Validation is only used if port is in mode “IOLINK MANUAL”
Note 2) Mandatory for GET request, C for POST request
Note 3) Mandatory for GET request, O for POST request. For POST the deviceName shall have no white space
(see also 4.4.3). Duplicate names shall lead to Error 207 (see A.2)
Note 4) If the applied value for cycle time cannot exactly be mapped, the port shall use the next possible lower
value.
434
435 Example:
436 Request
HTTP://192.168.178.22/iolink/v1/masters/1/ports/1/configuration
437 Response
{
"mode": "IOLINK_MANUAL",
"validationAndBackup": "TYPE_COMPATIBLE_DEVICE_V1.1",
"pin2Configuration": "DIGITAL_INPUT",
"cycleTime": {
"value": 2.3,
"unit": "ms"
},
"vendorId": 26,
"deviceId": 333,
"deviceName": "Distance_sensor_1"
}
438
439 5.6.5 POST /configuration

440 This is for writing the wanted port configuration
441 Table 42 – POST /configuration

442
Description
Description writes the wanted configuration for a specific port

If the applied value for cycle time cannot exactly be mapped, the port shall use the next
possible lower value.
By changing the configuration the communication to the device can get lost
Path parameters –
Errors 201, 202, 203, 204, 205, 206, 207, 302, 303 (see A.2), see 4.4.9
Request body object defined in Table 41 – Object PortConfiguration
Response body –
443
444 Example:
445 Request
HTTP://192.168.178.22/iolink/v1/masters/1/ports/1/configuration
{
"mode": "IOLINK_AUTOSTART",
"validationAndBackup": "TYPE_COMPATIBLE_DEVICE_V1.1",
"pin2Configuration": "ANALOG_INPUT",
"cycleTime": {
"value": 2.3,
"unit": "ms"
},
"vendorId": 26,
"deviceId": 333,
"deviceName": "Distance_sensor_1"
}
446
447 5.6.6 GET /datastorage

448 Getting the datastorage content (bulk data format is described [1]), added by the header
449 (VendorId, DeviceId, Revision ID).
450 Table 43 – GET /datastorage

451
Description
Description Read the actual datastorage content of the port

If no datastorage content is available the response is empty.
Path parameters –
Errors 302, 303 (see A.2), see 4.4.9
Success 200 OK
Request body –
Response body Object defined in Table 44 – Object Datastorage
452
453
454 Table 44 – Object Datastorage

455
object Datastorage
header object Object defined in Table Object is empty if there is no M

45 – Object datastorage content.
DataStorageHeader
content string Base 64 coded String is empty if there is no M
datastorage content.
see [7] , see [1] E6
456
457 Table 45 – Object DataStorageHeader
458
object Data Storage Header

vendorId number see [1] M
deviceId number see [1] M
ioLinkRevision string Enumeration see [1] M

“1.0”
“1.1”
459
460 Example:
461 Request
HTTP://192.168.178.22/iolink/v1/masters/1/ports/1/datastorage
462 Response
{
"header": {
"vendorId": 15,
"deviceId": 65253,
"ioLinkRevision": "1.1"
},
"content": "dasdASDasddaSdASdASdasDasdASdasDASdasasd"
}
463
464 5.6.7 POST /datastorage

465 Writing the datastorage content (bulk data format is described [1]), added by the header
466 (VendorId, DeviceId, Revision ID).
467
468 Table 46 – POST /datastorage

469
Description
Description Write datastorage content of the port

After receiving the datastorage content the port is restarted if the port is in mode
“Backup&Restore” or “Restore” see also [1] and see 5.6.5
Path parameters –
Errors 201, 202, 203, 204, 205, 206, 302, 401(see A.2), see 4.4.9
Request body Object defined in Table 44 – Object Datastorage
Response body –
470
471 Example:
472 Request
POST iolink/v1/masters/1/ports/1/datastorage
{
"header": {
"vendorId": 15,
"deviceId": 65253,
},
"content": "dasdASDasddaSdASdASdasDasdASdasDASdasasd"
}
473
474 5.7 Devices

475 Devices are addressed by device names. See port configuration in 5.6.5. for device name
476 assignement. If no device name is assigned the default name is used.
477 Example:
478 Addressing by default device name (e.g. device is on port 6 of master1)
HTTP://192.168.178.22/iolink/v1/devices/master1port6
479 Addressing by assigned device name (e.g. sensor34)
HTTP://192.168.178.22/iolink/v1/devices/sensor34
480
481 5.7.1 GET /

482 Get all available deviceName keys and the location by master number and port number
483 Table 47 – GET /devices

484
Description
Description read all available deviceName keys and the location by master number and port number
Path parameters –
Success 200 OK
Request body -
Response body Array of object defined in Table 48 – Object DeviceName
485
486 Table 48 – Object DeviceName

487
object DeviceName
deviceName string Device name is according 4.4.5 M
masterNumber number Integer 1..n M
portNumber number Integer 1..n M
488
489 Example:
490 Request
GET /iolink/v1/devices
491 Response
[
{
"deviceName": "DT35",
"masterNumber": 1,
"portNumber": 1
},
{
"deviceName": "TAD081",
"masterNumber": 1,
"portNumber": 2
},
{
"deviceName": "BNI_IOL",
"masterNumber": 1,
"portNumber": 3
},
{
"deviceName": "master1port4",
"masterNumber": 1,
"portNumber": 4
}
]
492
493
494
495 Table 49 – Resources Devices
496
/devices/{deviceName} Method
capabilities
/capabilities 5.7.2 GET Read the capabilities of the specific device M
Identification
/identification 5.7.3 GET Read the identification of the specific device M
/identification 5.7.4 POST Write application specific identification to the M
device
Process data
/processdata/value 5.7.5 GET Read the process data value of the specified M
device
format “byteArray” or “iodd” is given by a
query string
/processdata/value 5.7.6 POST Write the process data to the specified device M
format “byteArray” or “iodd” is given by the
request body
Parameter information
1)
/parameters 5.7.7 GET Read all available parameter indices and C
parameter names of the specific device.
IODD support is required.
/parameters 5.7.8 GET Read all available parameter sub-indices and C 1)
/{index}/subindices sub-parameter names of the specific device.
IODD support.is required
/parameters 5.7.9 GET Read all available parameter sub-indices and C 1)
/{parameterName}/subindices sub-parameter names of the specific device
(referenced by parameter name). IODD
support.is required.
Parameter values
/parameters 5.7.10 GET Read a parameter value of the specific device M
/{index}/value with the given index.
The requested format “byteArray” or “iodd” is
given by a query string
/parameters 5.7.11 GET Read a parameter value of the specific device M
/{index}/subindices with the given index and subindex.
/{subindex}/value The requested format “byteArray” or “iodd” is
given by a query string
/parameters 5.7.12 GET Read a parameter value of the specific device C1
/{parameterName}/value by parameter name.

IODD support is required
/parameters 5.7.13 GET Read a parameter value of the specific device C1
/{ parameterName } by parameter name and subname.
/subindices IODD support is required.
/{subParametername}/value
/parameters 5.7.14 POST Write a parameter value with the given index M
/{index}/value to the specified device.
The format is given within the body .
/parameters 5.7.15 POST Write a parameter value by name to the C1
/{parameterName}/value specified device.
The format is given within the body.
IODD support is required.
/parameters 5.7.16 POST Write a parameter value with the given index M
/{index}/subindices and subindex to the specified device.
/{subindex}/value The format is given within the body.
/parameters 5.7.17 POST Write a parameter value to the specific device C1

/{parameterName}/ by the parameter name and subname.
/subindices The format is given within the body.
/{subParameterName}/value IODD support is required.
/blockparameterization 5.7.18 POST Writing or reading one or more parameters by M

using the block parameterization method. The
format can be byteArray or iodd based.
Events
/events 5.7.19 GET reading the EventLog filtered for a specific M
device
Note 1) M if IODD support is available
497

499 Read the capabilities of the specific device

501
Description
Description Read the capabilities of the specific device

Path parameters –
Errors 302, 303, 304, 308 (see A.2), see 4.4.9
Success 200 OK
Request body –
Response body Object defined in Table 51 – Object DeviceCapabilities
502
503 Table 51 – Object DeviceCapabilities

504
object Device capabilities
minimumCycleTime object object defined in Table 108 – M

Object CycleTime
505
506 Example
507 Request
GET /iolink/v1/devices/sensor34/capabilities
508 Response
{
"minimumCycleTime": {
"value": 2.3,
"unit": "ms"
}
}
509

511 Read the identification of the device at the specified port

513
Description
Description Read the identification of the device

Path parameters –
Errors 302, 303, 304, 308 (see A.2), see 4.4.9
Success 200 OK
Request body –
Response body Object defined in Table 53 – Object Device Identification Get
514
515 Table 53 – Object Device Identification Get

516
object Device Identification GET
1)
vendorId number see [1] M
deviceId number see [1] M
ioLinkRevision string see [1] M
vendorName string see [1] C
vendorText string see [1] C
productName string see [1] C
productText string see [1] C
serialNumber string see [1] C
hardwareRevision string see [1] C
firmwareRevision string see [1] C
applicationSpecificTag string see [1] C
locationTag string see [1] C
functionTag string see [1] C

Note 1) M/O/C regarding [1]
517
518 Example:
519 Request
GET /iolink/v1/devices/sensor34/identification
520 Response
{
"vendorId": 26,
"deviceId": 42,
"ioLinkRevision": "1.1",
"vendorName": "SICK AG",
"vendorText": "Sensor Intelligence.",
"productName": "WTxx16",
"productId": "PROD-123456",
"productText": "Light switch",
"serialNumber": "IOLM123456",
"hardwareRevision": "3.2.1.444R",
"firmwareRevision": "3.2.1.888R",
"applicationSpecificTag": "Fallback light switch at the end of the belt",
"functionTag": "Check end of belt"
}
521
522 5.7.4 POST /identification

523 Writes device specific tags including applicationspecificTag, the locationTag and the
524 functionTag (see [1]) if available.
525 Table 54 – POST /identification

526
Description
Description write all identification data of an IO-Link master

Path parameters –
Errors 302, 303, 304, 309, 310 (see A.2), see 4.4.9
Request body –
Response body Object defined in Table 55 – Object DeviceIdentificationPOST
527
528 Table 55 – Object DeviceIdentificationPOST

529
object DeviceIdentificationPOST
1)
applicationSpecificTag string see [1] O
locationTag string see [1] O
functionTag string see [1] O
Note 1) M/O/C regarding [1]
530
531 Example:
532 Request
POST /iolink/v1/devices/sensor34/identification
{
"applicationSpecificTag": "Fallback light switch at the end of the belt",
"functionTag": "Check start of belt"
}
533
534 5.7.5 GET /processdata/value

535 Read the process data value of the specified device. The request format can be byteArray or
536 IODD based. If IODD format is requested the IODD feature has to be supported.
537 Process data can always accessed by addressing a device even if no physical device is
538 attached at the port. Process data comprises digital inputs on PIN 2 and PIN 4 (also if the
539 device is in “SIO” mode) as well as IO-Link process data if the port is in communication.
540 For getting process data 3 different modes indicated by “content” can be used. Typically input
541 process data are read, indicated by content “measure”. Additionally wanted output data
542 (usually set by POST) can be read back by content “control”. Also a combination of both
543 directions can be used indicated by content “measurecontrol”.
544
545 Table 56 – GET / processdata/value

546
Description
Description Read the process data (input data and optionally the output data) of the specified
device.
The requested format is indicated by a query string and can be byteArray (default) or
IODD based.
The requested content is indicated by a query string and can be measure, control or
measurecontrol
Path parameters –
Query parameters Format request parameters (see Table 57) and process data content parameters )see
Table 58)
Success 200 OK
Request body –
Response body Object defined in Table 59 – Object ProcessDataInOut
547
548
549 Table 57 – format request query parameters

550
format Enumeration: Default is byteArray

byteArray
iodd
551
552 Table 58 – process data content query parameters

553
content Enumeration: measure (default) is reading only input data from a

measure sensor device
control control is reading back output data to an actuator
device
measurecontrol
measurecontrol is reading input data and reading
back of output data of a device
554
555
556 Table 59 – Object ProcessDataInOut

557
object ProcessDataInOut
measure object Object defined in Table 60 – Object C1

ProcessData
control object Object defined in Table 60 – Object C2
ProcessData
Note 1) if there are process input data, the process data content is “measure” or “measurecontrol”
Note 2) if there are process output data, the process data content is “control” or “measurecontrol”
558
559 Table 60 – Object ProcessData

560
object ProcessData
ioLink object Object defined in Table 61 – C1

Object processDataIOL
pin2Value boolean true, false true = + 24 Volt C2
Pin4Value boolean true, false true = + 24 Volt C3
Note 1) If port is in IO-Link mode and device is connected

Note 2) If Pin 2 is available and configured as digital input for GET or configured as digital output for POST
Note 3) If Pin 4 is available and configured as digital input for GET or configured as digital output for POST
561
562 Table 61 – Object processDataIOL

563
object processDataIOL
valid boolean true,false For output data valid is M

always true.
value array numbers Byte array, see 4.4.7 order in big endian C1
value boolean, simple types C2

string,
number
value object Object defined in Table 70 – Object C3
complexParameterValue
Note 1) If format is byteArray
Note 2) If format is iodd and process data are of simple type, naming shall be according 4.4.5
Note 3) If format is “iodd” and process data are of complex type, naming shall be according 4.4.5
564
565 Examples:
566 Device is a sensor in IO-Link communication, Pin 2 is available and configured as digital input
567 The IO-Link process data is 0xC16D8 = 792280dez
568 Request (format is byteArray, content is measure).
GET
/iolink/v1/devices/master1port6/processdata/value?format=byteArray&content=measure
569 Response
{
"measure": {
"ioLink": {
"valid": true,
"value": [12,22,216]
},
"pin2Value": true
}
}
570
571 Device is a sensor in IO-Link communication and Pin 2 is available configured as a digital
572 input. The process data are of simple type.
573 Request (format IODD, content is measure).
GET /iolink/v1/devices/master1port6/processdata/value?format=iodd&content=measure
574 Response
{
"measure": {
"ioLink": {
"valid": true,
"value": 15.2
},
"pin2Value": true
}
}
575
576 Device is a sensor in IO-Link communication and Pin 2 is available configured as a digital
577 input. The process data are of complex type
578 Request (format IODD, content is measure).
579 Response
{
"measure": {
"ioLink": {
"valid": true,
"value": {
"Distance": 55,
"Quality": 12
}
},
"pin2Value": true
}
}
580
581 Device is a sensor in SIO Mode, Pin 2 and PIN 4 are available and configured as digital inputs
582 Request (format IODD, content is input).
583 Response
{
"measure": {
"pin2Value": true,
"pin4Value": false
}
}
584
585 Device is a sensor/actuator in IO-Link communication, Pin 2 is available and configured as a

586 digital input.
587 Request (format byteArray, content is measurecontrol)
GET
/iolink/v1/devices/master1port6/processdata/value?format=byteArray&content=measurecon
trol
588 Response
{
"measure": {
"ioLink": {
"valid": true,
"value": [12,22,216]
},
"pin2Value": false
},
"control": {
"ioLink": {
"valid": true,
"value": [128,221,134]
}
}
}
589
590 Device is a sensor/actuator in IO-Link communication, Pin 2 is available and configured as a

591 digital input.
592 Request (format IODD, content is measurecontrol)
GET
/iolink/v1/devices/master1port6/processdata/value?format=iodd&content=measurecontrol
593 Response
{
"measure": {
"ioLink": {
"valid": true,
"value": {"Pressure": 1.2}
},
"pin2Value": false
},
"control": {
"ioLink": {
"valid": true,
"value": {"Temperature": 50}
}
}
}
594
595 5.7.6 POST /processdata/value

596 Write the process output data to the specified device. Process data can also be written by
597 addressing a device even if no physical device is attached at the port but Pin2 or PIN 4 are
598 available. The device is addressed by the device name (see 4.4.3)
599
600 Table 62 – POST /processdata/value

601
Description
Description Write the process output data to the specified device. The requested format is implicit
defined within the body. No query parameters are needed.
System Behaviour if there are no restrictions process data will be updated
Path parameters –
Errors 201, 202, 203, 204, 205, 206, 302, 303, 304, 307, 308, 501, 502, 503, 601 (see A.2), see
4.4.9
Request body Object defined in Table 60 – Object ProcessData
Response body –
602
603 Examples:
604 Device is an actuator in IO-Link communication, Pin 2 is available and configured as a digital
605 output.
606 Request (implicit format byteArray)
POST /iolink/v1/devices/master1port6/processdata/value
{
"pin2Value": false,
"ioLink": {
"valid": true,
"value": [12,22,216]
}
}
607
609 output. Process data is of simple type
610 Request (implicit format IODD, simple type)
{
"pin2Value": true,
"ioLink": {
"valid": true,
"value": 32.4
}
}
611
613 output. Process data are of complex type
614 Request (implicit format IODD, complex type)
{
"pin2Value": true,
"ioLink": {
"valid": true,
"value": {
"Valve_1": true,
"Valve_2": false
}
}
}
615
616
617 5.7.7 GET /parameters

618 Read all available parameter indices and parameter names of the specific device. IODD
619 support is required.
620 Table 63 – GET /parameters

621
Description
Description Reads a list of all available parameters of a device

Path parameters –
Errors 302,303,304 (see A.2), see 4.4.9
Success 200 OK
Request body –
Response body Array of object defined in Table 64 – Object parameterList
622
623 Table 64 – Object parameterList
624
object parameterList
1)
index integer M
parameterName string Name of parameter see 4.4.5 M
Note 1) regarding the service itself which is conditional to IODD support
625
626 Example:
627 Request
GET /iolink/v1/devices/sensor34/parameters
628 Response
[
{
"index": 10,
"parameterName": "Vendor_Name"
},
{
"index": 12,
"parameterName": "Product_Name"
},
{
"index": 13,
"parameterName": "ProductID"
}
]
629
630 5.7.8 GET /parameters/{index}/subindices

631 Get all the available parameter sub-indices, sub-parameter names (referenced by Index
632 number). IODD support is required
633
634 Table 65 – GET /parameters/{index}/subindices

635
Description
Description Get all the available parameter sub-indices, sub-parameter names (referenced by Index
number).
Path parameters –
Errors 302, 303, 304, 308, 309 (see A.2), see 4.4.9
Success 200 OK
Request body –
Response body Array of object defined in Table 66 – Object deviceSubParameters
636
637 Table 66 – Object deviceSubParameters
638
object deviceSubParameters
property type value remark M/O/C 1)
subIndex integer M
subParameterName string Name of sub parameter see 4.4.5 M
Note 1) regarding the service itself which is conditional to IODD support
639
640 Example:
641 Request
GET /iolink/v1/devices/sensor34/parameters/64/subindices
642 Response
[
{
"subIndex": 1,
"subParameterName": "switching_mode"
},
{
"subIndex": 2,
"subParameterName": "switching_value_on"
},
{
"subIndex": 3,
"subParameterName": " switching_value_off"
}
]
643
644 5.7.9 GET /parameters/{parameterName}/subindices

645 Get all the available parameter sub-indices, sub-parameter names (referenced by parameter
646 name). IODD support required.
647 Table 67 – GET /parameters/{parameterName}/subindices

648
Description
Description Get all the available parameter sub-indices, sub-parameter names (referenced by
parameter name).
Path parameters –
Errors 302, 303, 304, 308, 309, 312 (see A.2), see 4.4.9
Success 200 OK
Request body –
Response body Array of object defined in Table 66 – Object deviceSubParameters
649
650
651 Example:
652 A device has a parameter named “Switch_properties” with some sub indices.
653 Request
GET /iolink/v1/devices/sensor34/parameters/Switch_properties/subindices
654 Response
[
{
"subIndex": 1,
"subParameterName": "switching_mode"
},
{
"subIndex": 2,
"subParameterName": "switching_value_on"
},
{
"subIndex": 3,
"subParameterName": " switching_value_off"
}
655
656 5.7.10 GET /parameters/{index}/value

657 This function reads a specific parametervalue and its sub-parameter values with the given
658 index from the specified device. The requested format is indicated by a query string and can
659 be byteArray (default) or IODD based. For format “iodd” the IODD support is needed
660
661 Table 68 – GET /parameters/{index}/value

662
Description
Description reads a specific parameter and its sub-parameter values with the given index from the
specified device
Path parameters –
Query parameters See Table 57
Errors 302, 303, 304, 308, 309, 310, 311, 601 (see A.2), see 4.4.9
Success 200 OK
Request body –
Response body one of objects that are listed as options in the deviceParameterValues object list (see
Table 69)
663
664 Table 69 – deviceParameterValues object list
665
deviceParameterValues object list
object Object defined in Table 72 – Object rawParameterValue C1

object Object defined in Table 71 – Object simpleParameterValue C2
object Object defined in Table 70 – Object complexParameterValue C3
Note 1) If format is byteArray
Note 2) If format is iodd and process data are of simple type, naming shall be according 4.4.5
Note 3) only available for indices or process data with complex data types
666
667 Table 70 – Object complexParameterValue

668
object complexParameterValue

{parameterName} object Object defined in Table 71 – Complex type e.g.
Object simpleParameterValue "Distance": {"value": 15 },
"Quality": {"value": 12 }
Note 4) IODDname is based on rules see 4.4.5
669
670
671
672 Table 71 – Object simpleParameterValue
673
object simpleParameterValue

value boolean, Simple types e.g. "value":15.2
string,
number
674
675 Table 72 – Object rawParameterValue

676
object rawParameterValue
value array see 4.4.7

numbers
677
678 Example:
679 Request (format byteArray)
GET /iolink/v1/devices/sensor34/parameters/65/value/?format=byteArray
680 Response
{
"value":[0,156,125,25]
}
681
682 Request (format iodd)
GET /iolink/v1/devices/sensor34/parameters/65/value/?format=iodd
683 Response (simple type)
{
"value":15.2
}
684
GET /iolink/v1/devices/sensor34/parameters/65/value/?format=iodd
686 Response (complex type)
{
"Distance": {"value": 15 },
}
687
688 5.7.11 GET /parameters/{index}/subindices/{subindex}/value

689 This function reads the value of a specific sub parameter with the given index and subindex
690 from the specified device. The requested format is indicated by a query string and can be
691 byteArray (default) or IODD based. For format “iodd” the IODD support is needed
692
693 Table 73 – GET /parameters/{index}/subindices/{subindex}/value

694
Description
Description reads a specific sub parameter value with the given index and subindex
Path parameters –
Query parameters See Table 57
Errors 302, 303, 304, 308, 309, 310, 311, 601 (see A.2), see 4.4.9
Success 200 OK
Request body –
Table 69)
695
696
697 Example
GET /iolink/v1/devices/sensor34/parameters/25/subindices/3/value/?format=byteArray
699 Response
{
"value":[0,156,125,25]
}
700
GET /iolink/v1/devices/sensor34/parameters/25/subindices/3/value/?format=iodd
702 Response
{
"value":15.2
}
703
704 5.7.12 GET /parameters/{parameterName}/value

705 This function reads a specific parameter value with the given name .The response is also
706 given by IODD naming. The parameterName shall follow the rules of IODD based naming
707 rules (see 4.4.5). IODD support is needed.
708 Table 74 – GET /parameters/{parameterName}/value

709
Description
Description reads a specific parameter value with the given name

Path parameters –
Query parameters Format request parameters (see Table 57)
Success 200 OK
Request body –
Table 69)
710
711 Example
GET /iolink/v1/devices/sensor34/parameters/nameOfVariable/value/?format=byteArray
713 Response
{
"value":[0,156,125,25]
}
714
GET /iolink/v1/devices/sensor34/parameters/nameOfVariable/value/?format=iodd
716 Response (simple type)
{
"value":15.2
}
717
GET /iolink/v1/devices/sensor34/parameters/nameOfVariable/value/?format=iodd
719 Response (complex type)
{
"Distance": {"value": 15 },
}
720
721 5.7.13 GET /parameters/{parameterName}/subindices/{subParameterName}/value

722 This function reads the content of a specific sub parameter value with the given name and
723 subname from the specified device.
724
725 Table 75 – GET /parameters/{parameterName}/subindices/{subParameterName}/value

726
Description
Description reads the content of a specific sub parameter value with the given name and subname
Path parameters –
Query parameters Format request parameters (see Table 57)
Errors 312 (see A.2) ), see 4.4.9
Success 200 OK
Request body –
Table 69)
727
728
729 Example
GET
/iolink/v1/devices/sensor34/parameters/nameOfVariable/subindices/subName/value?format
= byteArray
731
732 Response
{
"value":[0,156,125,25]
}
733
GET
/iolink/v1/devices/sensor34/parameters/nameOfVariable/subindices/subName/value?format
= iodd
735 Response
{
"value": 152
}
736
737
738 5.7.14 POST /parameters/{index}/value

739 This function writes the parameter with the given index to the specified device. The format is
740 given within the body
741 Table 76 – POST /parameters/{index}/value

742
Description
Description writes the parameter with the given index

Path parameters –
Errors (see A.2), ), see 4.4.9
Request body one of objects that are listed as options in the deviceParameterValues object list (see
Table 69)
Response body –
743
744
745 Example
POST /iolink/v1/devices/sensor34/parameters/125/value
{
"value":[0,156,125,25]
}
746
747 Example
{
"value": 15
}
748
749 Example
{
"Distance": {"value": 15},
"Quality": {"value": 12}
}
750
751 5.7.15 POST /parameters/{parameterName}/value

752 This function writes the parameter with the given name to the specified device. The format is
753 given within the body
754 Table 77 – POST /parameters/{parameterName}/value

755
Description
Description writes the parameter with the given name to the specified device
System Behaviour if there are no restrictions parameter will be updated
Path parameters –
Errors 312 (see A.2) ), see 4.4.9
Table 69)
Response body –
756
757 Example
POST /iolink/v1/devices/sensor34/parameters/variableName/value
{
"value":[0,156,125,25]
}
758
759
{
"value": 15
}
760
761
{
"Distance": {"value": 15},
"Quality": {"value": 12}
}
762
763 5.7.16 POST /parameters/{index}/subindices{subindex}/value

764 Write the parameter with the given index and subindex to the specified device. The format is
765 given within the body.
766
767 Table 78 – POST /parameters/{index}/subindices{subindex}value

768
Description
Description writes the sub parameter with the given name

Path parameters –
Errors 302, 303, 304, 308, 309, 205, 206, 501 (see A.2), ), see 4.4.9
Table 69)
Response body –
769
770 Example
POST /iolink/v1/devices/sensor34/parameters/35/subindices/4/value
{
"value":[0,156,125,25]
}
771
772 5.7.17 POST /parameters/{parameterName}/subindices{subParameterName}/value

773 This function writes the sub-parameter with the given parameter name and
774 subParameterName to the specified device.
775 Table 79 – POST /parameters/{ parameterName }/subindices{ subParameterName }value

776
Description
Description writes the sub-parameter with the given parameter name and subParameterName. The
requested format is implicit defined within the body

Path parameters –
Errors 205, 206, 302, 303, 304, 308, 309, 312, 501 (see A.2), see 4.4.9
Table 69)
Response body –
777
778 Example
POST /iolink/v1/devices/sensor34/parameters/35/subindices/4/value
{
"value": 152
}
779
780 5.7.18 POST /blockparametrization

781 Writing or reading one or more parameters by using the block parameterization method see
782 [1]. The request format can be byteArray or iodd based.
783 Table 80 – POST /blockparametrization

784
Description
Description Writing or reading one or more parameters as a block (consitent)

System Behaviour if there are no restrictions for writing the objects will be modified
Path parameters –
Query parameters Format request parameters see Table 57
Success 200 OK for “read”
204 No Content for “write”
Request body Object defined in Table 81 – Object BlockparametrizationRequest
Response body Array of Object defined in Table 82 – Object BlockparametrizationReadResponse
785
786 Table 81 – Object BlockparametrizationRequest

787
object BlockparametrizationReadRequest
direction string Enumeration: M

“read”
“write”
parameters objects Object defines in Table 83 – Addresses all parameters or M
Object ParameterAddress subParameters
788
789 Table 82 – Object BlockparametrizationReadResponse

790
791
object BlockparametrizationReadResponse

object Object defines in Table 83 – Object M
ParameterAddress
object Object defined in Table 84 – Object M
ParameterValue
792
793 Table 83 – Object ParameterAddress

794
795
object ParameterAddress

address object Object defined in Table 85 – C1
Object IndexAddress
address object Object defined in Table 86 – C1

Object SubIndexAddress
Note 1: Either one one of them has to be used
796
797 Table 84 – Object ParameterValue

798
799
object ParameterAddress
value array numbers See 4.4.7 C1
value boolean, Simple types C2

string,
number
value object Object defined in Table 70 – Object Complex types C3
complexParameterValue
Note 1: this is format byteArray
Note 2: this is for format iodd
Note 2: this is for format iodd but not for subindex/subparameter access
800
801
802
803 Table 85 – Object IndexAddress

804
805
object IndexAddress
index number integer Number of index C1

e.g. {"index": 123}
parameterName string {parameterName} Name of Index C2

{"parameterName":
"Application_tag"}

Note 2: this is format iodd if iodd is supported
806
807 Table 86 – Object SubIndexAddress

808
809
object SubIndexAddress

index number integer C1
subIndex number integer C1
parameterName string {parameterName} C2
parameterSubName string {parametersubName} C2

Note 2: this is format iodd if iodd is supported
810
811 Example:
812 Read Request (format byteArray)
POST /iolink/v1/devices/sensor34/blockparametrization/?format=byteArray
{
"direction": "read",
"parameters": [
{
"address": {"index": 123}
},
{
"address": {"index": 233,"subIndex": 2}
}
]
}
813 Response (request format is byteArray)
{
[
{
"address": {"index": 123},
"value": [15,232,22]
},
{
"address": {"index": 233,"subIndex": 2},
"value": [23,149,206]
}
]
}
814
815 Read Request (format is iodd)

POST /iolink/v1/devices/sensor34/blockparametrization/?format=iodd
{
"direction": "read",
"parameters": [
{
"address": {"parameterName": "applicationTag"}
},
{
"address": {"{"parameterName": "hystersis","subParametername": "channelB" }
}
]
}
816 Response
{
[
{
"address": {"parameterName": "Application_tag"},
"value": {"value": "Level 2, row 3"}
},
{
"address": {"parameterName": "Hysteresis","subParameterName": "Channel_B"},
"value": {"value": 123}
}
]
}
817
818 Write Request (format is byteArray)
POST /iolink/v1/devices/sensor34/blockparametrization/?format=byteArray
{
"direction": "write",
"parameters": [
{
"address": {"index": 123},
"value": [15,232,22]
},
{
"address": {"index": 233,"subIndex": 2},
"value": [23,149,206]
}
]
}
819
820 Write Request (format iodd)
POST /iolink/v1/devices/sensor34/blockparametrization/?format=iodd
{
"direction": "write",
"parameters": [
{
"address": {"parameterName": "Application_tag"},
"value": {"value": "Level 2, row 3"}
},
{
"address": {"parameterName": "Hysteresis","subParameterName": "Channel_B"},
"value": {"value": 123}
}
]
}
821
822 5.7.19 GET /events

823 This is for reading the EventLog for a specific device and similar to the reading of the
824 EventLog but filtered for this specific device (origin is device).
825 Table 87 – GET /events

826
Description
Description This is for reading the EventLog for a specific device

System Behaviour Nothing will be changed or modified.
Path parameters –
Query parameters Device Event log query parameters (see Table 88)
Success 200 OK
Request body –
Response body Object defined in Table 20 – Object GatewayEventLog
827
828 Table 88 – DeviceEvent log query parameters

829
top 1…n Delivers the oldest n events of the event Log.

top is mutually exclusive to bottom.
bottom 1…m Delivers the latest n events of the event lOG.
bottom is mutually exclusive to top.
830
831 Example:
832 Request
GET /iolink/v1/devices/Temp_sensor_1/events
833 Response
[
{
"time": "2018-05-18T07:31:54.123Z",
"origin": {
"master": 1,
"port": 1,
"device": "Temp_sensor_1"
},
"message": {
"code": 16912,
"mode": "APPEARED",
}
}
]
834
835 5.8 IODD

836 Within the feature IODD the IODDs are stored (uploading) on the gateway.
837 For a specific device (referenced by VendorID and Device ID) only one version of an
838 IODD shall be stored.
839 All request marked as (M) are mandatory if the feature IODD is supported
840
841 Table 89 – Resources for IODDs

842
Method
/iodds 5.8.1 GET Get a list of all IODD (representations) that are M
available on the gateway
/iodds 5.8.2 POST Update or create an IODD M
/iodds/vendors/{vendorId}/d 5.8.4 GET Get a specific IODD O
evices/{deviceId}/revisions/
{ioLinkRevision}
/iodds/vendors/{vendorId}/d 5.8.3 DELETE Delete a specific IODD representation M

evices/{deviceId}/revisions/
{ioLinkRevision}
843
844 5.8.1 GET /iodds

845 Get a list of all IODDs (representations) that are available on the gateway.
846 Table 90 – GET /iodds

847
Description
Description Get a list of all IODDs (representations) that are available on the gateway.
Path parameters –
Success 200 OK
Request body –
Response body Array of objects defined in Table 91 – Object IODDIdentification
848
849 Table 91 – Object IODDIdentification

850
Object IODDIdentification

vendorId Integer see [1] M
deviceId Integer see [1] M
version string see [1] M
releaseDate string see [1] M
ioLinkRevision string Enumeration: see [1] M

“1.0”
“1.1”
851
852 Example:
853 Request
GET /iolink/v1/iodds
854 Response
[
{
"vendorId": 1234,
"deviceId": 4567,
"version": "4.3",
"releaseDate": "2018-01-02",
},
{
"vendorid": 4321,
"deviceId": 8765,
"version": "2.1",
"releaseDate": "2015-01-02",
}
]
855
856 5.8.2 POST /iodds

857 Update or create an IODD on the gateway. Application Type is XML
858 Table 92 – POST /iodds

859
Description
Description Update or create an IODD on the gateway

Path parameters –
Errors 602, 603, 604, 605 (see A.2), see 4.4.9
Request body –
Response body –
860
861
862 5.8.3 DELETE /iodds

863 Delete a specific IODD on the gateway. The IODD is addressed by path parameters.
864 Table 93 – DELETE /iodds

865
Description
Description deletes an IODD on the gateway

Path parameters /vendors/{vendorId}/devices/{deviceId}/revisions/{ioLinkRevision}
Errors 301, 305, 306, 601(see A.2), see 4.4.9

Request body –
Response body –
866
867 Example:
868 Request
DELETE /iolink/v1/iodds/vendors/26/devices/34654/revisions/1.1
869
870
871 5.8.4 GET /iodds

872 Read a specific IODD (XML file) from the gateway. The IODD is addressed by path
873 parameters.
874
875 Table 94 – GET /iodds

876
Description
Description Read a specific IODD (XML file) from the gateway.

Path parameters /vendors/{vendorId}/devices/{deviceId}/revisions/{ioLinkRevision}
Errors 301,601 (see A.2), see 4.4.9
Success 200 OK
Request body –
Response body –
877
878 Example:
879 Request
GET /iolink/v1/iodds/vendors/26/devices/34654/revisions/1.1
880
881 5.9 MQTT

882 This section is related to the configuration of the MQTT Publisher defining publishing topics
883 and configurations for addressing the MQTT broker. All is referenced to MQTT Version 3.1.1
884
885 All request marked as (M) are mandatory if the MQTT feature is supported.
886
887 Table 95 – Resources MQTT configuration
888
URLs clause HTTP remark M/O/C
/mqtt Method
/configuration 5.9.1 GET Read the MQTT configuration of the gateway M

/configuration 5.9.2 POST Update the MQTT configuration of the gateway M
/topics 5.9.3 GET Get the list of MQTT topics M
/topics 5.9.4 POST Create a new MQTT topic M

/topics/{topicId} 5.9.5 DELETE Delete a specific MQTT topic M
/topics/{topicId} 5.9.6 GET Get one specific MQTT topic M
889
890 5.9.1 GET /mqtt/configuration

891 Read the MQTT configuration of the gateway by getting the object “MQTT Configuration” . For
892 details of MQTT protocol and client configuration see [6]
893
894 Table 96 – GET /mqtt/configuration
895
Description
Description Read the MQTT configuration

Path parameters –
Errors 101, 102, 103 (see A.2)
Success 200 OK
Request body –
Response body Object defined in Table 97 – Object MQTTConfiguration
896
897
898 Table 97 – Object MQTTConfiguration
899
object MQTT Base Configuration

brokerAddress string url of the broker M
username string M
password string M
lastWill object Object defined in Table 98 M

– Object LastWill
keepAliveTime number M
900
901 Table 98 – Object LastWill

902
object Last Will
topic string M
message string M
qoS string Enumeration: M

“0_ONLY_ONCE”
“1_AT_LEAST_ONCE”
“2_EXACTLY_ONCE”
retain boolean true, false M
903
904 Example:
905 Request
GET /iolink/v1/mqtt/configuration
906 Response
{
"brokerAddress": "192.168.2.1/mqttbroker",
"username": "iolink_json",
"password": "1234",
"lastWill": {
"topic": "my_temperature_sensor",
"message": " Process data transfer stopped ",
"qoS": "0_ONLY_ONCE",
"retain": true
},
"keepAliveTime": 0
}
907
908 5.9.2 POST /mqtt/configuration
909 Write the MQTT configuration to the gateway by updating the object “MQTT Configuration”
910
911 Table 99 – POST /mqtt/configuration
912
Description
Description writes the MQTT configuration to the gateway

System Behaviour if there are no restrictions the configuration will be updated
Path parameters –
Errors 101,102, 103, 150, 201, 202, 203, 204, 205, 206 (see A.2)
Success 200 OK
Request body Object defined in Table 97 – Object MQTTConfiguration
Response body –
913
914 Example:
915 Request
POST /iolink/v1/mqtt/configuration
{
"brokerAddress": "192.168.2.1/mqttbroker",
"username": "iolink_json",
"password": "1234",
"lastWill": {
"topic": "my_temperature_sensor",
"message": " Process data transfer stopped ",
"qoS": "0_ONLY_ONCE",
"retain": true
},
"keepAliveTime": 0
}
916
917 5.9.3 GET /mqtt/topics

918 Get the list of MQTT topics. Supported MQTT topics are of type processData or event.
919 Table 100 – GET /mqtt/topics

920
Description
Description Read the list of MQTT topics

Path parameters –
Errors 101, 102, 103 (see A.2)
Success 200 OK
Request body –
Response body Array of objects defined in Table 101 – Object MQTTtopic
921
922
923 Table 101 – Object MQTTtopic

924
object MQTTtopic

topicId number The topic number as a M2
reference
topicName string M
qoS string Enumeration: M

“0_ONLY_ONCE”
“1_AT_LEAST_ONCE”
“2_EXACTLY_ONCE”
deviceName string {deviceName} M
processData object MQTT ProcessData topic C1

see Table 102
event object null C1
Note 1: Either one of processData or event

Note 2: This is not applicable for POST
925
926 Table 102 – Object MQTT ProcessDataTopic

927
object MQTT ProcessDataTopic
direction string Enumeration: M

“measure”
“control”
“measurecontrol”
format string Enumeration: M
“byteArray”
“iodd”
interval object “CycleTime” see C1
Table 108
onChange Boolean true, false C1
Note 1: Either one of interval or onChange
928
929 Example:
930 Request
GET /iolink/v1/mqtt/topics
931 Response
[
{
"topicId": 1,
"topicName": "PD inPOST",
"qos": "At least once",
"qos": "1_AT_LEAST_ONCE",
"processData": {
"direction": "measure",
"format": "iodd",
"interval": {
"value": 10,
"unit": "ms"
}
}
},
{
"topicId": 2,
"topicName": "Event",
"qos": "2_EXACTLY_ONCE",
"deviceName": "TAD081",
"event": null
},
{
"topicId": 3,
"topicName": "PD",
"qos": "0_ONLY_ONCE",
"deviceName": "BNI_IOL",
"processData": {
"direction": "measurecontrol",
"format": "iodd",
"onChange": true
}
}
]
932
933
934 5.9.4 POST /mqtt/topics

935 Create one new MQTT topic on the gateway
936
937 Table 103 – POST /mqtt/topics

938
Description
Description Create a new MQTT topic on the gateway

Path parameters –
Errors 102 (see A.2)
Success 200 OK
Request body Object defined in Table 101 – Object MQTTtopic
Response body –
939
940 Example :
941 Request
POST /iolink/v1/mqtt/topics
{
"qos": "1_AT_LEAST_ONCE",
"processData": {
"format": "iodd",
"interval": {
"value": 10,
"unit": "ms"
}
}
}
942 5.9.5 DELETE /mqtt/topics/{topicID}

943 Delete a specific MQTT topic on the gateway referenced by the topic ID. The topic ID is
944 addressed by a path parameter.
945 Table 104 – DELETE /mqtt

946
Description
Description Deletes a MQTT topic

System Behaviour if there are no restrictions the topic will be deleted
Path parameters /topics/{topicID}
Errors 101,102, 103, 150 (see A.2)
Request body –
Response body –
947
948 Example:
949 Request
DELETE /iolink/v1/mqtt/topics/2
950
951
952 5.9.6 GET /mqtt/topics/{topicId}

953 Read one specific MQTT topic on the gateway referenced by the topic ID.
954 Table 105 – GET /mqtt/topics

955
Description
Description Read one specific MQTT topic

Path parameters /{topicID}
Errors 101, 102, 103 (see A.2)
Success 200 OK
Request body –
Response body Object defined in Table 101 – Object MQTTtopic
956 Example:
957 Request
GET /iolink/v1/mqtt/topics/2
958 Response
{
{
"topicId": 2,
"topicName": "PD inPOST",
"qos": "1_AT_LEAST_ONCE ",
"processData": {
"format": "iodd",
"interval": {
"value": 10,
"unit": "ms"
}
}
}
959
960
961 6 MQTT topics format

962 This section describes the publishing format for the topic. Topics can be either be of type
963 processData or event.
964 For process data the topic format is as a object defined in Table 59 – Object
965 ProcessDataInOut
966 Example: (Process data topic)

967
{
"measure": {
"ioLink": {
"valid": true,
"value": {
"Distance": 55,
"Quality": 12
}
},
"pin2Value": true
}
}
968
969 For Event_Log entries the topic format is as a object defined Table 20 – Object
970 GatewayEventLog. Only one EventLog entry shall be published at the time the event was
971 entered into the EventLog.
972
973 Example: (Event Log entry topic)

974
{
"time": "2018-05-18T07:31:54.123Z",
"origin": {
"master": 1,
"port": 1,
"device": "Temp_sensor_1"
},
"message": {
"code": 16912,
"mode": "APPEARED",
}
}
975
976
977 Annex A
978 (normative)
979
980 Status Codes and Errors on HTTP
981 A.1 HTTP Status Codes
982 Each request on HTTP can response with or without an error indicated bey the status code.
983 Table 106 – HTTP Status codes

984
Status Code description
200 OK The request completed successfully

201 Created A new resource has been created successfully
204 No Content Response code for POST requests without content in response and
the DELETE.
400 Bad Request
403 Forbidden The user is not permitted to perform the requested operation
404 Not Found The requested resource did not exist
500 Server error
985
986 A.2 JSON Errors

987 Each negative response indicated by a HTTP status code other than 200 is added by an
988 individual JSON Error object.
989 Table 107 – JSON Error codes

990
Error HTTP JSON Message Notes
Code Status
code
General errors
101 500 Internal server error
102 500 Internal communication error
103 404 Operation not supported
104 400 Action locked by another client Note 1
150 403 Permission denied Note 2
JSON parsing errors
201 400 Parsing failed (error while parsing the incoming JSON value)
202 400 Invalid data (given for the value, e.g. malformed IP address)
203 400 Invalid JSON data type (e.g. string instead of numbers)
204 400 Unknown enumeration value
205 400 Value out of range (exceeds the minimum or maximum value)
206 400 Out of bounds (an array/string was accessed exceeding its maximum length)
207 400 Duplicated deviceName
Resource access errors
301 404 Resource not found (e.g. wrong URL).
302 404 masterNumber not found
303 404 portNumber not found
304 404 deviceName not found
305 400 Incorrect query parameter name

306 400 Incorrect query parameter value
307 400 Port is not configured in IOLINK_MANUAL or IOLINK_AUTOSTART mode.
308 404 IO-Link Device is not accessible (not connected or communication error)
309 404 IO-Link parameter not found
310 404 IO-Link parameter access not supported by the device
311 400 IO-Link parameter access error Note 3
312 404 IO-Link parameter name is not unique
Please use the [name]_[index] format
Data Storage errors
401 400 Mismatch between configured device and data storage meta data
Process Data handling errors
501 400 Writing processdata to Pin 2 is not possible. Pin 2 is not configured as
DIGITAL_OUTPUT
502 400 Writing processdata to Pin 4 is not possible. Pin 4 is not configured as
DIGITAL_OUTPUT
503 400 Attached IO-Link device has no output process data
IODD errors
601 400 IODD is not available.
602 500 Unable to upload IODD XML file. Insufficient memory space
603 400 Uploaded file is no valid IODD XML. Upload rejected
604 400 Uploaded file is no valid IODD XML. CRC check failed. Upload rejected
605 400 Uploaded file is no valid IODD XML. Parsing failed. Upload rejected
Data content errors
701 400 Incomplete data set
702 400 Data set not applicable (not supported), the whole data set is rejected
703 400 Incompatible data set combination, the whole data set is rejected
Note 1: (e.g. by a fieldbus controller)
Note 2: (e.g. due to user management)
Note 3: The additional iolinkErrorCode and iolinkErrorMessage fields contain the IO-Link error code and the
incident text from the ErrorTypes table
991
992 Annex B
993 (normative)
994
995 JSON base objects
996 B.1 General JSON objects
997 B.1.1 Cycle time object
998
999 Table 108 – Object CycleTime

1000
object Cycle Time

value number M
unit string “ms” Milliseconds M
1001
1002 Example:
{
"value": 2.3,
"unit": "ms"
}
1003
1004 B.1.2 Error object

1005
1006 Table 109 – Object Error
1007
object Error

msgCode number Integer value M
message string See A.2, M

See [1]
1008
1009 Example:
{
"msgCode": 150,
"message": "Permission denied"
}
1010
1011 B.1.3 Power Supply object

1012
1013 Table 110 – Object PowerSupply

1014
object PowerSupply
value number M
unit string “A” SI unit Ampere M
1015
1016 Example:
{
"value": 0.3,
"unit": "A"
}
1017
1018
1019 Bibliography
1020
1021 [1] IO-Link Community, IO-Link Interface and System, V1.1.3, July 2019, Order No.
1022 10.002
1023 [2] IO-Link Community, IO Device Description (IODD), Version 1.1, Order No. 10.012
1024 [3] https://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf
1025 [4] DIN ISO 8601 https://www.iso.org/iso-8601-date-and-time-format.html
1026 [5] RFC 5424 Syslog Protocol https://tools.ietf.org/html/rfc5424
1027 [6] www.oasis-open.org
1028 [7] IETF RFC 4648 https://www.ietf.org/rfc/rfc4648.txt
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056  Copyright by:

1057
1058 IO-Link Community

1059 c/o PROFIBUS Nutzerorganisation e.V.
1060 Haid-und-Neu-Str. 7
1061 76131 Karlsruhe
1062 Germany
1063 Phone: +49 (0) 721 / 96 58 590
1064 Fax: +49 (0) 721 / 96 58 589
1065 e-mail: info@io-link.com
1066 http://www.io-link.com/
1067
1068
1069
1070
1071
1072
1073
1074

JSON Integration 10222 d099 Jul19

Uploaded by

Copyright:

Available Formats

You might also like

JSON Integration 10222 d099 Jul19

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

JSON Integration 10222 d099 Jul19

Uploaded by

Copyright:

Available Formats

JSON

Order No: 10.222

File name: JSON_Integration_10222_d099_Jul19

This specification has been prepared by the IO-Link community.

® is a registered trademark. It may be used only by the members of the IO-Link

1 Motivation and scope ....................................................................................................... 9

5.6.7 POST /datastorage ........................................................................................ 33

Figure 1 – Physical Master models ....................................................................................... 11

Table 1 – IODD text conversion rules examples .................................................................... 13

Table 43 – GET /datastorage ................................................................................................ 32

Table 85 – Object IndexAddress ........................................................................................... 55

7 0.2 Patent declaration

Patent number [xx] Title

18 Information may be obtained from:

[xx] Name and address of patent holder

27 IO-Link JSON Mapping

38 This document describes a REST API

40 b) for IODD file management (up/download).

41 c) for MQTT client configuration.

48 IO-Link Community, IO-Link System Description – Technology and Application, Version

54 3 Terms, definitions, symbols, abbreviated terms and conventions

80 3.2 Symbols and abbreviated terms

86 3.3.2 Meaning of M/O/C

92 4 Architectural and technical scope

100 Figure 1 – Physical Master models

103 4.2 Security

106 4.3 Device data and layer model

111 Figure 2 – Device layer model

116 4.4 General rules

118 4.4.1 Master numbering

120 4.4.2 Port numbering

122 4.4.3 Device Naming

127 3. The definition of duplicated device names has to be rejected.

129 5. A device names maximum length is 32 characters minimum length is 1 character.

”master2port4” is the default name of an device connected to port 4 of master 2

132 4.4.4 Access rights

138 4.4.5 Naming based on IODD

145 Rule 2: Special characters get replaced by „_“

146 Rule 3: Leading numbers shall be prefixed with „_“

150 Rule 5: Naming according the scheme {name}_{index} or {name}_{subindex} is always

154 Table 1 – IODD text conversion rules examples

IODD text Name ISDU Unique name (Name_Index)

0815 variable _0815_variable 3452 _0815_variable_3452

Note 1) this is a naming conflict (duplicate)

156 4.4.6 Data Type conversion

159 Table 2 – Data type conversion

IO-Link data type JSON data type

161 4.4.7 Byte Array conversion

168 Table 3 – Mapping example of a bit sequence

value (bin) bit length value (hex) Byte Array (dec)

10 0111 6 0x27 [39]

100 0000 15 0x40F0 [64, 240]

171 4.4.8 Time format

176 The format for absolute time is JJJJ-MM-TTThh:mm:ss.fZ

177 Time format for relative time is P[JY][MM][WW][TD][T[hH][mM][s[.f]S]]

Absolute time: 2018-05-18T07:31:54.123Z

180 4.4.9 Error Behaviour

184 Following general rules apply for the error handling: