IDS NXT User manual

IDS NXT
IDS Imaging Development Systems GmbH
Dimbacher Str. 6-8
D-74182 Obersulm, Germany
T: [phone]
E: [e-mail]
W: http://www.ids-nxt.com
REST interface
for IDS NXT SDK 2.1.0 / IDS NXT OS 1.1.0

March 2021 2
IDS NXT: REST interface
Contents
1 Preface .............................................................................................................................................. 5
2 Symbols and hints ............................................................................................................................ 6
3 Introduction ...................................................................................................................................... 7
3.1 Version hint ................................................................................................................................. 7
3.2 User authentication ...................................................................................................................... 7
3.3 Units ........................................................................................................................................... 7
3.4 Types ......................................................................................................................................... 7
3.5 Implemented services ................................................................................................................... 8
4 User control ...................................................................................................................................... 9
4.1 /users ......................................................................................................................................... 9
4.2 /users/<existing-username> .......................................................................................................... 9
5 Device events .................................................................................................................................. 11
5.1 /events ...................................................................................................................................... 11
5.2 Server sent events ..................................................................................................................... 12
5.3 Event syntax .............................................................................................................................. 12
5.4 Restrictions ............................................................................................................................... 12
6 Device information .......................................................................................................................... 13
6.1 /deviceinfo ................................................................................................................................ 13
6.2 /deviceinfo/avatar ....................................................................................................................... 16
6.3 /deviceinfo/datetime ................................................................................................................... 17
7 GPIO ............................................................................................................................................... 19
7.1 /gpio ......................................................................................................................................... 19
7.2 /gpio/inputs ............................................................................................................................... 19
7.3 /gpio/inputs/<pin> ...................................................................................................................... 19
7.4 /gpio/outputs .............................................................................................................................. 20
7.5 /gpio/outputs/<pin> .................................................................................................................... 20
8 Camera settings .............................................................................................................................. 22
8.1 /camera .................................................................................................................................... 22
8.2 /camera/trigger .......................................................................................................................... 24
8.3 /camera/image .......................................................................................................................... 27
8.4 /camera/roi ............................................................................................................................... 27
8.5 /camera/color ............................................................................................................................ 28

March 2021 3
IDS NXT: REST interface
9 Light ................................................................................................................................................ 31
9.1 /light ......................................................................................................................................... 31
9.2 /light/external ............................................................................................................................. 31
9.3 Flash modes (external light) ........................................................................................................ 32
10 Network settings ........................................................................................................................... 34
10.1 /network .................................................................................................................................. 34
10.2 /network/ipv4 ........................................................................................................................... 35
10.3 /network/nameservers ............................................................................................................... 36
10.4 /network/timeserver .................................................................................................................. 37
10.5 /network/ssl ............................................................................................................................. 37
11 RS-232 ........................................................................................................................................... 39
11.1 /rs232 ..................................................................................................................................... 39
11.2 /rs232/data .............................................................................................................................. 40
12 Signals .......................................................................................................................................... 42
12.1 /signals ................................................................................................................................... 42
12.2 /signals/list ............................................................................................................................... 42
12.3 /signals/list/<id> ....................................................................................................................... 43
13 Statistics ....................................................................................................................................... 45
13.1 /statistics ................................................................................................................................. 45
13.2 /statistics/change ..................................................................................................................... 46
14 Support file .................................................................................................................................... 48
15 System status (REST) ................................................................................................................... 49
15.1 /states ..................................................................................................................................... 49
15.2 /states/<identifier> ................................................................................................................... 49
16 Vision app list ................................................................................................................................ 51
16.1 /vapps ..................................................................................................................................... 51
16.2 /vapps/activated ....................................................................................................................... 51
16.3 /vapps/activated/<vapp> ........................................................................................................... 52
16.4 /vapps/<newVApp> .................................................................................................................. 52
17 Individual vision apps .................................................................................................................... 54
17.1 Actions .................................................................................................................................... 55
17.1.1 /vapps/<vapp>/actions ................................................................................................... 55
17.1.2 /vapps/<vapp>/actions/<action> ..................................................................................... 56
17.2 Avatar ..................................................................................................................................... 56

March 2021 4
IDS NXT: REST interface
17.3 Configurables .......................................................................................................................... 57
17.4 Files ........................................................................................................................................ 58
17.4.1 /vapps/<vapp>/files ....................................................................................................... 58
17.4.2 /vapps/<vapp>/files/<file> .............................................................................................. 59
17.4.3 /vapps/<vapp>/files/<file>/data ....................................................................................... 60
17.5 Images .................................................................................................................................... 60
17.5.1 /vapps/<vapp>/images ................................................................................................... 60
17.5.2 /vapps/<vapp>/images/<image> ..................................................................................... 60
17.6 License ................................................................................................................................... 61
17.7 Log ......................................................................................................................................... 62
17.8 ResultSinks .............................................................................................................................. 62
17.8.1 /vapps/<vapp>/resultsinks .............................................................................................. 62
17.8.2 /vapps/<vapp>/resultsinks/<sink> ................................................................................... 62
17.9 ResultSources ......................................................................................................................... 63
17.9.1 /vapps/<vapp>/resultsources .......................................................................................... 64
17.9.2 /vapps/<vapp>/resultsources/dummy .............................................................................. 64
17.9.3 /vapps/<vapp>/resultsources/last .................................................................................... 65
17.9.4 /vapps/<vapp>/resultsources/list ..................................................................................... 66
17.9.5 /vapps/<vapp>/resultsources/list/<key> ........................................................................... 66
17.10 ROI ....................................................................................................................................... 68
17.10.1 /vapps/<vapp>/rois ...................................................................................................... 68
17.10.2 /vapps/<vapp>/rois/<roi> ............................................................................................. 68
Index .................................................................................................................................................. 71

March 2021 5
IDS NXT: REST interface
1 Preface
Introduction
IDS Imaging Development Systems GmbH has taken every possible care in preparing this manual. We
however assume no liability for the content, completeness or quality of the information contained therein. The
content of this manual is regularly updated and adapted to reflect the current status of the software. We
furthermore do not guarantee that this product will function without errors, even if the stated specifications are
adhered to.
Under no circumstances can we guarantee that a particular objective can be achieved with the purchase of
this product.
Insofar as permitted under statutory regulations, we assume no liability for direct damage, indirect damage or
damages suffered by third parties resulting from the purchase of this product. In no event shall any liability
exceed the purchase price of the product.
Please note that the content of this manual is neither part of any previous or existing agreement, promise,
representation or legal relationship, nor an alteration or amendment thereof. All obligations of IDS Imaging
Development Systems GmbH result from the respective contract of sale, which also includes the complete and
exclusively applicable warranty regulations. These contractual warranty regulations are neither extended nor
limited by the information contained in this manual. Should you require further information on this product, or
encounter specific problems that are not discussed in sufficient detail in the manual, please contact your local
dealer or system installer.
Trademarks
The IDS logo is a registered trademark of IDS Imaging Development Systems GmbH,
registered for U.S. (Reg.No. 4,513,138) and other countries.
IDS NXT and uEye are registered trademarks of IDS Imaging Development Systems
GmbH. Microsoft and Windows are trademarks or registered trademarks of Microsoft Corporation. All other
products or company names mentioned in this manual are used solely for purposes of identification or
description and may be trademarks or registered trademarks of the respective owners.
Copyright
© IDS Imaging Development Systems GmbH. All rights reserved. This manual may not be reproduced,
transmitted or translated to another language, either as a whole or in parts, without the prior written permission
of IDS Imaging Development Systems GmbH.
Status: March 2021
Contact
Visit our web site http://www.ids-nxt.com where you will find all the latest information about our software and
hardware products. Please contact your local IDS distributors for first level support in your language. For a list
of IDS distributors worldwide please go to our website http://www.ids-nxt.com.
Address
IDS Imaging Development Systems GmbH
Dimbacher Str. 6-8
D-74182 Obersulm, Germany
T
[phone]
E
[e-mail]
W
http://www.ids-nxt.com

March 2021 6
IDS NXT: REST interface
2 Symbols and hints
This symbol indicates hints with useful information for better understanding and using
features and functions.
This symbol indicates important warnings for product safety to prevent damage.

March 2021 7
IDS NXT: REST interface
3 Introduction
This documentation describes the REST interface (REST = Representational State Transfer) for IDS NXT
cameras. The REST interface allows you to send requests or commands such as GET or PUT etc. via HTTP
commands or to access data.
3.1 Version hint
The REST interface uses HTTP/1.1, other HTTP versions are not supported.
This document describes functions that are not available on every device, depending on the
model version / firmware version.
3.2 User authentication
User authentication is carried out using HTTP Basic.
The sub-pages specify the required user classes, split by HTTP method. The three default users are specified
with color coding.
· User:
· Service:
· Admin (displayed as "Administrator"):
The following group authorizations exist:
Available with no group restriction and without authentication
Write parameters
Read parameters
(De)activate and (un)install vision apps
Set important device parameters and update
The default password for each user class is "ids". When you log in for the first time, you
must change the password to be able to log in. If you log in with the administrator profile, you
can change the passwords for the user classes "Service" and "User". This procedure is
described in the IDS NXT cockpit manual.
If you have not changed the default password, an error message "HTTP 901 Access denial
through default password" is returned for a REST request.
3.3 Units
Units of values are specified as "Unit". Units should be lower case compound SI units (with prefix) or "pixel". A
GUI should detect these units and display the correct localized version ("1000 millimeters" could be displayed
as "39.37 inch" in US-us and as "1 Meter" in De-de). Other units are possible, but in this case the GUI should
adopt them directly; localization is carried out using the Accept-Language-Header (translation only, not
conversion in this case). Specifying a unit is optional. If no unit is specified, the number is to be viewed as
dimensionless. A further unit is RFC 2822, which displays the specified date format.
3.4 Types
The following types are possible:
Type
Qt/C++ equivalent
String
QString
StringList
QStringList

March 2021 8
IDS NXT: REST interface
Type
Qt/C++ equivalent
Integer
qint64
Boolean
bool
Double
double
3.5 Implemented services
Variable paths are specified in angle brackets (e.g. <appname>) and match [a-zA-Z]+[_a-zA-Z0-9-]*
The (partially exemplary) response to an OPTIONS request is shown here.
GET, DELETE etc. relate to the possible HTTP methods for the specified address. The JSON objects in the
level below specify the permitted or available MIME types. If no MIME type is specified, there is no restriction
here (for example for DELETE with blank response). Below the MIME types, there is then an Allowed=true and
a description. Variables provided are below values with description, name (used as the JSON object name)
and type (String, StringList -> JSonArray of Strings, Int) and, where appropriate, range (either array of
possible discrete values or minimum/maximum values). Values that are included in the URL as GET
parameters are flagged as "Parameters" (e.g. /camera/image?quality=50).
Unless otherwise specified, the default MIME type for POST/PUT/PATCH is application/x-www-
formurlencoded: The parameters/values are transferred in the same way as in an HTML form (in the body with
Parameter=Value&SecondParameter=Value2).
If using application/x-www-form-urlencoded, the URL coding (percentage coding) must be used for special
characters, i.e. a space character is specified with "%20", etc.
The "Objects" array lists all subpaths. (For example the "avatar" object for /deviceinfo can be called
using /deviceinfo/avatar)
The possibility of using OPTIONS is only specified if this represents a variation from the default behavior
(application/json no parameters).

March 2021 9
IDS NXT: REST interface
4 User control
Creating and deleting users, and changing group association is currently deactivated on the device side.
· /users
· /users/<existing-username>
4.1 /users
· OPTIONS
· GET
{
"GET": {
"application/json": {
"Allowed": true,
"Description": "Receive user list",
"Values": {
"Users": {
"Description": "List of Usernames",
"Name": "Users",
"Type": "StringList"
}
}
}
},
"Objects": [
"admin",
"service",
"user"
]
}
Comments
Objects are existing users.
4.2 /users/<existing-username>
· OPTIONS , or own user name
· GET , or own user name
· PATCH , or own user name
{
"GET": {
"application/json": {
"Allowed": true,
"Description": "Receive user information",
"Values": {
"Groups": {
"Description": "List of group memberships",
"Type": "StringList"
}
}
}
},

March 2021 10
IDS NXT: REST interface
"Objects": [
"admin",
"writeparam",
"readparam",
"modvapp"
],
"PATCH": {
"application/x-www-form-urlencoded": {
"Allowed": true,
"Description": "Modifies the user",
"Values": {
"Password": {
"Description": "New password",
"Type": "String"
}
}
}
}
}
Comments
Objects are group names and have no REST answers.

March 2021 11
IDS NXT: REST interface
5 Device events
· /events
· Server sent events
· Event syntax
· Restrictions
5.1 /events
· GET
Events can be transferred using the device event resource "/events". The client makes a one-off GET request
for /events and then receives the events in the body of the response. Chunked transfer encoding is used to
enable the events to be sent regardless of the time of the GET request. Only signals occurring after receipt of
the GET request are transferred. To identify that events are actively being monitored, receipt of the response
header on the client side can be used.

March 2021 12
IDS NXT: REST interface
5.2 Server sent events
In addition to the proprietary interface (deprecated), the events can also be requested using SSE. To do this,
the request must include an HTTP header (Accept: text/eventstream) and the events (see Event syntax) are
then transferred in the data block.
GET /events HTTP/1.1
Accept: text/eventstream
HTTP/1.1 200 OK
Content-Type: text/eventstream
data:GET /camera/image
data:GET /statistics
data:GET /statistics
5.3 Event syntax
The event contains the method and URL that has changed. This is used to avoid having to retrieve the
OPTIONS after every change.
Example
GET /deviceinfo
OPTIONS /vapps/<vapp>/configurables
5.4 Restrictions
There are some resources (paths) that are not covered by the event channel. These are:
Path
Restriction
Justification
/deviceinfo
System information (temperature,
RAM, etc.)
CPU is updated with event.
The values are only determined
when requested
These values can be requested cyclically.

March 2021 13
IDS NXT: REST interface
6 Device information
· /deviceinfo
· /deviceinfo/avatar
· /deviceinfo/datetime
6.1 /deviceinfo
· OPTIONS
· GET
· PATCH
{
"GET": {
"application/json": {
"Description": "Receive device information",
"Values": {
"CPULoad": {
"Description": "Total CPU load",
"Range": {
"Maximum": 100,
"Minimum": 0
},
"Type": "Double",
"Unit": "Per cent"
},
"Color": {
"Description": "True if color model.",
"Type": "Boolean"
},
"DateTime": {
"Description": "Server time. Must be of format 'RFC 2822 date' e.g.
'Fri, 1 Jan 2021 00:00:00 UTC'",
"Type": "String"
},
"DeviceModel": {
"Description": "Model of the device",
"Type": "String"
},
"DeviceName": {
"Description": "Given name of the device",
"Type": "String"
},
"DeviceType": {
"Description": "Type of the device",
"Type": "String"
},
"DiskLoad": {
"Description": "Total disk load.",
"Range": {
"Maximum": 100,
"Minimum": 0
},
"RangeWarning0": {
"Maximum": 100,

March 2021 14
IDS NXT: REST interface
"Minimum": 75
},
"Type": "Double",
"Unit": "Per cent"
},
"FPS": {
"Description": "Frames per seconds, average.",
"Type": "Double",
"Unit": "fps"
},
"Language": {
"Description": "Default language",
"Range": [
"en"
],
"Type": "String"
},
"Location": {
"Description": "Given location of the device",
"Type": "String"
},
"NetworkRx": {
"Description": "Bytes received over Network per second",
"Type": "Integer",
"Unit": "bytes per second"
},
"NetworkTx": {
"Description": "Bytes sent over Network per second",
"Type": "Integer",
"Unit": "bytes per second"
},
"RAMLoad": {
"Description": "Total RAM load.",
"Range": {
"Maximum": 100,
"Minimum": 0
},
"Type": "Double",
"Unit": "per cent"
},
"Serialnumber": {
"Description": "Serial number of the device",
"Type": "String"
},
"Temperature": {
"Description": "Device temperature in degrees celcius",
"Range": {
"Maximum": 120,
"Minimum": -5
},
"RangeError0": {
"Maximum": -5,
"Minimum": -5
},
"RangeError1": {
"Maximum": 120,
"Minimum": 91
},

March 2021 15
IDS NXT: REST interface
"RangeWarning0": {
"Maximum": 0,
"Minimum": -5
},
"RangeWarning1": {
"Maximum": 91,
"Minimum": 78
},
"Type": "Double",
"Unit": "Degrees Celsius"
},
"UniqueID": {
"Description": "Unique-ID, used for device identification",
"Type": "String"
},
"Uptime": {
"Description": "Uptime in seconds",
"Type": "Integer"
},
"VSupply": {
"Description": "Supply voltage",
"Range": {
"Maximum": 50,
"Minimum": 10
},
"RangeError0": {
"Maximum": 11,
"Minimum": 10
},
"RangeError1": {
"Maximum": 50,
"Minimum": 30
},
"RangeWarning0": {
"Maximum": 30,
"Minimum": 28
},
"RangeWarning1": {
"Maximum": 11.5,
"Minimum": 11
},
"Type": "Double",
"Unit": "volt"
},
"Version": {
"Description": "Firmware-Version of the device",
"Type": "String"
}
}
}
},
"Objects": [
"avatar"
"datetime"
],
"PATCH": {
"application/x-www-form-urlencoded": {
"Description": "Update the device infos."

March 2021 16
IDS NXT: REST interface
"Values": {
"DateTime": {
"Description": "Server time",
"Type": "String"
},
"DeviceName": {
"Description": "Given name of the device",
"Type": "String"
},
"Language": {
"Description": "Default language",
"Range": [
"en"
],
"Type": "String"
},
"Location": {
"Description": "Given location of the device",
"Type": "String"
}
}
}
}
}
6.2 /deviceinfo/avatar
· OPTIONS
· GET
· DELETE
· PUT
{
"DELETE": {
"Description": "Deleting the avatar. A fallback avatar will be used for next
access."
},
"GET": {
"image/png, image/bmp, image/jpeg": {
"Allowed": true,
"Description": "Receive the avatar image file."
"Parameters":{
"MaxHeight":{
"Description": "Maximal height of image.",
"Mandatory": false,
"Type": "Integer"
},
"MaxWidth":{
"Description": "Maximal width of image.",
"Mandatory": false,
"Type": "Integer"
},
"Quality":{
"Description": "Quality of image.",
"Mandatory": false,
"Type": "Integer"

March 2021 17
IDS NXT: REST interface
}
}
}
},
Options [
],
"PUT": {
"image/png, image/jpeg, image/gif, image/bmp": {
"Description": "Upload a new avatar, implicitly deleting the old one.
Image must be 256x256px."
}
}
}
6.3 /deviceinfo/datetime
· OPTIONS
· GET
· PATCH
{
"GET": {
"application/json": {
"Description": "Receive device datetime information",
"Values": {
"DateTime": {
"Description": "Server time",
"Type": "String"
},
"NTP": {
"Description": "True if NTP is enabled",
"Type": "Boolean"
},
"NTPServer": {
"Description": "Must be of format 'xxx.xxx.xxx.xxx'.",
"Type": "String"
},
"Timezone": {
"Description": "Current used Timezone",
"Range": [
"America/Adak",
"America/Anchorage",
...
"Asia/Yekaterinburg",
"Asia/Yeveran"
],
"Type": "String",
"Unit": "IANA timezone"
}
}
}
},
Options [
],
"PATCH": {
"application/json": {
"Description": "Update device datetime information.",

March 2021 18
IDS NXT: REST interface
"Values": {
"DateTime": {
"Description": "Server time",
"Type": "String"
},
"NTP": {
"Description": "True if NTP is enabled.",
"Type": "Boolean"
},
"NTPServer": {
"Description": " Must be of format 'xxx.xxx.xxx.xxx'.",
"Type": "String"
},
"Timezone": {
"Description": "Current used timezone",
"Range": [
"America/Adak",
"America/Anchorage",
...
"Asia/Yekaterinburg",
"Asia/Yeveran"
],
"Type": "String",
"Unit": "IANA timezone"
}
}
}
}
}

March 2021 19
IDS NXT: REST interface
7 GPIO
· /gpio
· /gpio/inputs
· /gpio/inputs/<pin>
· /gpio/outputs
· /gpio/outputs/<pin>
7.1 /gpio
· OPTIONS
{
"Objects": [
"inputs",
"outputs"
]
}
7.2 /gpio/inputs
· OPTIONS
{
"Objects": [
"in1",
"in2"
]
}
Comments
Objects are available pins, thus currently in1 or in2
7.3 /gpio/inputs/<pin>
· OPTIONS
· GET
· PATCH
{
"GET": {
"application/json": {
"Description": "Receive status information.",
"Values": {
"Inverter": {
"Description": "Enabled additional inverter. If true, 0V input means
on-level",
"Type": "Boolean"
},
"Level": {
"Description": "Logic-Level, note that true hardware level depends on
Invert",
"Type": "Boolean"
},

March 2021 20
IDS NXT: REST interface
"Title": {
"Description": "Pin title",
"Type": "String"
}
}
}
},
Options [
],
"PATCH": {
"application/x-www-form-urlencoded": {
"Description": "Update the GPIO settings.",
"Values": {
"Inverter": {
"Description": "Enabled additional inverter. If true, 0V input means
on-level",
"Type": "Boolean"
}
}
}
}
}
Comments
Only difference to /gpio/outputs/<pin>: Level cannot be set using PATCH.
7.4 /gpio/outputs
· OPTIONS
{
"Objects": [
"out1",
"out2"
]
}
Comments
Objects are available pins, thus currently out1 or out2
7.5 /gpio/outputs/<pin>
· OPTIONS
· GET
· PATCH
{
"GET": {
"application/json": {
"Description": "Receive status information.",
"Values": {
"Inverter": {
"Description": "Enabled additional inverter. If true, 0V input means
on-level",
"Type": "Boolean"
},