Blickwerk Color Sensor API documentation

Basic Information

Endpoint

http://{sensor}/api

sensor string, required	Hostname or IP address of the sensor

Home

Welcome to the Blickwerk Sensor API Documentation. The Blickwerk Sensor API allows you to query and manage all aspects of your Blickwerk color sensors.

Contact Information

Silicann Systems GmbH
Schillerplatz 10
D-18055 Rostock

Phone: +49 (0)381 - 36764120
Email: info@silicann.com

Overview

The HTTP based API enables users and system integrators to query and change the sensors configuration and state. It’s the primary interface and exposes numerous details about the sensors. It even is the foundation for other services found on the sensors like the integrated web application and the terminal interface available via RS232 and/or USB.

The HTTP API enables the integration in various toolchains and business processes supporting data collection, ERPs, backup and monitoring of your sensor fleet.

The HTTP API is REST oriented and uses HTTP verbs to distinguish actions of varying impact:

GET: Retrieve the current state of a resource (e.g. the current sample). GET requests are free of side-effects and sometimes cacheable.
POST: Create a new resource item or execute an action that changes the state of the sensor (e.g. execute autogain, teach a new color).
PUT: Modify a resource (e.g. changing the tolerance of a matcher).
DELETE: Delete, reset, or empty a resource (e.g. reset the settings, delete a color).

Manual Request Examples

The following examples are meant to give a basic understanding of the API. Most programming languages, operating systems, and browsers offer some way to interact with HTTP APIs. The list below is non-conclusive.

Recommended Tools for API Queries

Environment	Recommendations
CLI	cURL, Invoke-RestMethod (PowerShell)
Chrome/Chromium	Postman

Query Example

Every web browser uses GET requests to retrieve data from websites. With tools like curl it’s easy to send requests with other HTTP verbs as well. The following request:

curl -X GET http://sensor/api/sensor/samples/current

returns a JSON response like this:

{
 "data": {
  "timestamp": 3145601368.0,
  "uuid": "0f721d83-f3c0-4584-8913-a51a5b842784",
  "transformed_color": {
   "values": [ 99.953887939453125, -0.0064074993133544922, 0.017380714416503906 ]
  },
  "corrected_color": {
   "values": [ 0.79777300357818604, 0.74252212047576904, 0.28755432367324829 ]
  },
  "detection": {
   "matcher": null,
   "output_pattern": { "states": [ false, false, false ] },
   "distances": [ null, null, null ]
  },
  "representations": {
   "RGB": [ 0.9994870320649919, 0.99951960105113213, 0.99927028464270895 ]
  },
  "inputs": {
   "trigger_0_down": true,
   "trigger_1_down": true,
   "trigger_2_up": false,
   "trigger_0_up": false,
   "trigger_3_down": true,
   "trigger_3_up": false,
   "trigger_2_down": true,
   "trigger_1_up": false
  }
 },
 "errors": []
}

Quickstart

The following sequence of requests configures the sensor for the detection of a wanted color.

The request examples below are sent via the curl commandline tool (examples prefixed with $) or the Windows Powershell (prefixed with >).

The same requests can be used in all other programming languages or environments supporting HTTP requests, as well.

Clear all settings:

$ curl -X DELETE http://sensor/api/settings

> Invoke-RestMethod -Method DELETE -Uri http://<sensorIP>/api/settings

Place a neutral white color target in front of your sensor's optics.

Adjust the sensor settings to the optical setup by initiating the Autogain procedure:

$ curl -X POST http://<sensorIP>/api/sensor/detection-profiles/current/autogain

> Invoke-RestMethod -Method POST -Uri http://<sensorIP>/api/sensor/detection-profiles/current/autogain

Place your wanted target object in front of the sensor's optics.

Teach this color:

$ curl -X POST http://<sensorIP>/api/sensor/detectables

> Invoke-RestMethod -Method POST -Uri http://<sensorIP>/api/sensor/detectables

The sensor should now pull up its first output pin as long as the target is placed in front of it.
- The first switching output pin is assigned to the first color, by default. This is configurable.

Request the current sample data and pick only the color values:

# hint: "jq" is a separate tool for querying JSON datasets
$ curl http://<sensorIP>/api/sensor/samples/current | jq .data.transformed_color.values

> (Invoke-RestMethod -Method GET -Uri http://<sensorIP>/api/sensor/samples/current).data.transformed_color

Result:

[ 101.23353576660156, 7.889449596405029, -42.49897003173828 ]

Introduction

General information

Collections

can be queried with GET requests
some collections allow to be filtered via query parameters, outlined in the resource documentation below
some collections allow POST requests to create new items in the collection
- properties of new items can usually be set in the POST request body
- a failure to create a new item due to malformed data is indicated with a 400 HTTP status code
- a failure to create a new item caused by too many items in the collection is indicated by a 422 HTTP status code
- some collections can be depleted by sending a DELETE request to them supporting the same query parameters as GET requests if any
- a DELETE request on the collection always returns a positive HTTP status code like 200 or 204 with no regard for the number of items that have been deleted (and even if no items have been deleted as a result of the request)

Collection Items

Individual collection items typically can be accessed via a URL path like /collection-path/item-id (e.g. /api/access/users/barbara, where /users is the collection and barbara the item id).
- If no item with that specific id exists, either because it has been deleted in the meantime in response to a user request or (in case of size- or time-limited collections) the item was removed, the request will be terminated with a 404 HTTP status code.
- The data of some collections items can be updated with PUT requests where the body contains a JSON object with the data that should be updated. Partial updates are supported as well. Changing read-only attributes may be terminated with a 400 HTTP status code. The response for a successful update contains the state of the resource after the modification.
- The unique id of an item (most often a uuid) is invariable.
- Some collection items can be removed with a DELETE request.
Some collections support more than one URL-compatible item id field. The matcher, detectable and detection profile collection items for example, can also be retrieved by their respective alias field.

Data Formatting Conventions

Identifiers are in American English
Compound words in resource urls are hyphenated (e.g. white-reference)
Compound words in JSON objects or data accepted as multipart/form-data uses snake case (e.g. white_reference)

Response Format and Error Handling

The API will return a response containing a body with a JSON object for any given request to any known endpoint of the following form:

{
        "errors": [ ...errors ],
        "data": { ...data }
}

data contains the actual response payload that has been requested whereas errors contains any errors that the API encountered while processing the request. An error object found in the errors array has the following form:

{
        "message": String,
        "mapping": String | null,
        "code": String
}

message: The message property contains a human-readable english description of the error. Its primary target audience is the developer working with the API and should guide them on their way to resolve the error.
mapping: The mapping property contains a valid JavaScript expression as a string that evaluates to the property on the submitted or provided object where the error was encountered. The mapping may be null if no such connection can be made. If it is set an expression like foo[1].bar would refer to the bar property in the second item of an array named foo found on the root object.
code: The code property can be used as an identifier to distinguish between different error types. This may be helpful if you want to display localized error messages (where you could use code as the key to your translation dictionary) or when used in code to change the behaviour of your application in case of an error. The code is a string representing an error class hierarchy where each error class is delimited by a dot. This is helpful when you want to start of with little set of error translations and become more exact with the descriptions at a later point in time. So instead of translating a code like LPLC.validation.non_negative_float you could just translate LPLC.validation with 'Please check your input' and add a translation for float errors later on.

Error codes are documented for each resource below but the following are the most common ones:

LPLC.format.encoding.utf8
LPLC.format.malformed.json
LPLC.validation
LPLC.validation.boolean
LPLC.validation.missing_input
LPLC.validation.non_negative_float
LPLC.validation.non_negative_integer
LPLC.validation.positive_integer
LPLC.validation.readonly
LPLC.validation.single_character
LPLC.validation.smaller_integer
LPLC.validation.string

Switching outputs, triggers and hold time settings

Every sample period ends with the selection of the most appropriate matcher (''group of colors''). This matcher is applied to the switching outputs under certain conditions. Relevant configuration for this behavior are the following settings:

optional triggered update of switching outputs (see action-triggers)
matcher attributes hold_time and reset_output_after_hold_time_expired

The following situations and actions are used in the behavior specification below:

no active hold time: The hold_time attribute of the most recently applied matcher was zero. Thus there is currently no hold time configured until another matcher with a non-zero hold time is applied.
hold time is expired: The most recently applied matcher had a hold time greater than zero, but this hold time elapsed since this matcher was applied. Thus an hold time was previously active, but it expired in the meantime.
reset_output_after_hold_time_expired is on/off: When a matcher is applied (see below), then the attribute reset_output_after_hold_time_expired is memorized until another matcher is selected. The on/off state refers to this memorized value.
unchanged detected matcher: The most recently applied matcher and the currently detected matcher are the same.
new detected matcher: The most recently applied matcher and the currently detected matcher are not the same.
action do nothing: The switching outputs and the currently memorized hold time settings stay unchanged.
action apply new matcher: Memorize the matcher attributes hold_time and reset_output_after_hold_time_expired as current hold time settings and set the switching outputs as specified in the output_pattern of the matcher.
action apply 'no match': Memorize the detection profile attribute non_matching_hold_time as the current hold time. Memorize false for reset_output_after_hold_time_expired. Set the switching outputs as specified in the detection profile attribute non_matching_output.

The behaviour with and without triggered updates of switching outputs differs significantly. Thus both situations are specified separately below.

Disabled triggered update of switching outputs

Triggered updates are disabled if none of the trigger events (e.g. a rising edge of the first input line) is configured with the enable_switching_output action (see /api/actions).

The following table lists the specific behavior based on the currently active hold time settings and depending on the currently detected matcher.

Currently active hold time settings	Action for unchanged detected matcher	Action for new detected matcher
no active hold time	do nothing	apply new matcher
hold time is expired; reset_output_after_hold_time_expired is off	do nothing	apply new matcher
hold time is expired; reset_output_after_hold_time_expired is on	apply no match	apply no match
hold time is not expired	do nothing	do nothing

The following flowchart visualizes the decisions and actions when applying a matcher. It is a different representation of the table above. Hold time behavior without triggers

Enabled triggered update of switching outputs

Triggered updates are enabled if any of the trigger events (e.g. a rising edge of the first input line) is configured with the enable_switching_output action (see /api/actions)

The following flowchart visualizes the decisions and actions when applying a matcher.

Hold time behavior with triggers

Websockets

Introduction

The websocket provided by the API can be used to develop highly interactive frontends for the sensors that work without polling the endpoints of the REST-like resources.

Aside from a stream of samples that the sensors pushes to the websocket it also broadcasts information about events like newly taught colors or a change of the sensors configuration.

The websocket is developed as a complement to the resources and not as a replacement. The primary interface to control the sensor is and always will be the resources outlined below.

Requests to any of the endpoints under /websocket do not reset the session timeout.

Overview

You can access the websocket on the /websocket/notifications/websocket path. The data transmitted on this channel resembles a stream of information. In order to easily identify relevant packages, every payload transmitted through the socket is encapsulated in a JSON object containing the following properties:

id

The unique identifier of this particular websocket packet

source

The source this packet originates from or the reason for its transmission (e.g. detection_profile.matcher)

timestamp

The sensors uptime when the packet is sent over the websocket.

payload

An object containing an event property (with values like changed or created), and an optional uuid and data attribute that represent the object described by the event from the source.

One of the fields added_items, changed_items and removed_items may be present if source refers to a collection. In this case the value of this field is a list of identifiers belonging to the affected items of the collection. This allows clients to synchronize their data model without requesting the full collection after each collection-related notification. If a collection-related notification does not contain any of the fields above, then the scope of changes is unspecific and thus a full retrieval of the collection may be necessary.

Fallback

In order to support older Browsers the /websocket/notifications endpoint is compatible with the SockJS Client-Bibliothek library that implements fallback techniques like XHR Streaming, JSONP, Long Polling and others.

Networking and Discovery

Network discovery

The sensor announces itself in the local network via the following protocols:

zeroconf / avahi broadcasts
SSDP

The SSDP protocol allows discovery of the sensors via the Windows network neighborhood. The zeroconf protocol allows discovery on Linux, MacOS and mobile devices.

Automatically assigned link-local address

The sensor is reachable via its explicitly configured IPv4 and IPv6 addresses as well as via its automatically configured link-local address. This address belongs to the subnet "fe80::/10" with the local address part being based on the MAC address of the sensor (see "EUI-64"). The link-local address of the sensor is usable in all networks independent of the sensor configuration. Thus it provides a stable address under all circumstances.

Link-local addresses in general need to be suffixed with the local network identifier.

Examples:

Windows: fe80::1234:56ff:fe78:90ab%0
Linux / MacOS / Android: fe80::1234:56ff:fe78:90ab%eth0

The network identifier (suffix after "%") in the examples above need to be adjusted to the local setup of the device connecting to the sensor.

Resources

Device Information

Some constant properties describe the individual device itself and include information about the model and vendor.

Get Device Properties ¶
GET /device

Return invariable properties of the device

Response

Body

application/json

Properties (object)

data

DeviceInformation, required

DeviceInformation

id DeviceSerialNumber, required	Serial Number
model_name string, required	human-readable name of the device model
model_key string, required	unique id of the device model
variant any of string or null, required	indicates a special series of a model
vendor_key DeviceVendorKey, required	Unique key identifying the organization distributing this device
vendor_name DeviceVendorName, required	Name of vendor of this device
device_id DeviceSerialNumber, optional, Deprecated	Deprecated: use "id" instead.
model string, optional, Deprecated	Deprecated: use "model_name" instead.
vendor DeviceVendorName, optional, Deprecated	Deprecated: use "vendor_name" instead.

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Sensor

Query and modify all details of sensoric configuration and operation.

Retrieve Sensor Samples ¶
GET /sensor/samples Permission Scope sensor

Returns a list of samples from the color detection.

When no additional query parameters are passed the collection contains samples from the past. You can activate sample-streaming with the stream query parameter. In this case only new samples will be returned, as they become available.

Samples are implemented as ring buffer. Old samples will be removed from the collection as new samples are added.

Request

Query Parameters

stream number, one of [`0`, `1`] , default: `0`, optional	Controls whether or not stream-mode is activated. When streaming is activated only the sensor will contionously transmit new samples to the client. The number of samples that are transmitted can be controlled with the `stream_count` query parameter. When streaming is deactivated (which is the default), only past samples are returned.
stream_count integer , default: `0`, optional	Determines how many samples should be transmitted before the connection is terminated when stream-mode has been activated. The default is to stream indefinitely.
format string, one of [`json`, `csv`] , default: `json`, optional	Determines the output format of the samples when stream-mode has been activated. If `csv` is selected the first transmitted line are the column headers. Headers are based on the default JSON representation and use the syntax also used by JavaScript. Given the example `representations.RGB[0]` the value for this header would refer to the first item in the RGB representation.
delimiter string , default: `,`, minimum length: 1, maximum length: 1, optional	Determines the column delimiter when `csv` has been selected as output-format. If you want to use a semicolon as delimiter be sure to url-encode it first (`%3B`). Otherwise it’s interpreted as query parameter separator. Be aware that even though unicode characters are allowed by the API you should restrict yourself to one-byte characters as most tools will fail to use delimiters that use two or more bytes.

Response

Body

application/json

Properties (object)

data

object, required

data

samples

Array of ColorDetectionResult, required

ColorDetectionResult[]

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

timestamp

TimestampBackendUptime (number), required

The timestamp (given in microseconds) is based on the uptime of the internal analog sensor backend. It may get reset to zero under specific conditions.

corrected_color

CorrectedColor, required

Representation of a color in the colorspace XYZ.

corrected_color

values Array of number, minimum items: 3, maximum items: 3, required	Location in a colorspace

transformed_color

TransformedColor, required

A color represented by a coordinate in the colorspace. The array indices of the values property match the order of the colorspace.axes property of currently used detection profile.

transformed_color

values Array of number, minimum items: 3, maximum items: 3, required	Location in a colorspace

representations

ColorRepresentations, required

Pre-calculcated visual representations of a color suitable for rendering

representations

RGB Array of number, minimum items: 3, maximum items: 3, required	RGB color array representing the axes r, g, and b in that order. Values are floats between 0 and 1.

inputs

InputsState, required

The state of all inputs during a given period is specified by a list of possible events combined with a boolean value indicating, if the given event occurred within the period.

inputs

// boolean, required	The boolean value indicates whether the named input event occurred during the last period.

detection

ColorMatchingResult, required

After each sampling period the retrieved color value is compared to the stored detectables (color positions). Detectables are ignored, if the tolerance shape of their corresponding matcher does not encompass the current sample. Finally the closes suitable detectable is selected as the winner of the color matching operation. The corresponding matcher determines the state of the sensor for the duration of the next sampling period.

detection

matcher

any of UUID (string) or null, optional, Deprecated

Deprecated: use "chosen_matcher_id" instead

chosen_matcher_id

any of UUID (string) or null, required

unique identifier of the selected matcher

distances

Array of any of number or null, required

Distance between the sample's color position and the selected matcher's closest color position along the three axes of the color space.

The array contains three 'null' values, if no suitable matcher was found for the current color sample.

output_pattern

CurrentSwitchingOutputsState, required

Currently active state of the Switching Outputs. Beware that this may deviate from the specified output states of the current best matcher, since settings like triggered input or hold time influence update process for the Switching Outputs.

output_pattern

states Array of any of boolean or null, required	List of True/False values describing the current states of the Switching Outputs

signal_level

number, required

The signal level indicates the usage of the internal ADC sampling range. This

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Retrieve latest Sensor Sample ¶
GET /sensor/samples/current Permission Scope sensor

Returns the latest sample.

Be aware that the same sample may be returned for successive requests if no new samples arrived meanwhile. While the sensor is performing auto-gain or is over-saturated, it will return the last valid sample that was processed.

The result is empty (null), while the sensor is processing a configuration change request.

Response

Body

application/json

Properties (object)

data

any of ColorDetectionResult or null, required

ColorDetectionResult

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

timestamp

TimestampBackendUptime (number), required

The timestamp (given in microseconds) is based on the uptime of the internal analog sensor backend. It may get reset to zero under specific conditions.

corrected_color

CorrectedColor, required

Representation of a color in the colorspace XYZ.

corrected_color

values Array of number, minimum items: 3, maximum items: 3, required	Location in a colorspace

transformed_color

TransformedColor, required

A color represented by a coordinate in the colorspace. The array indices of the values property match the order of the colorspace.axes property of currently used detection profile.

transformed_color

values Array of number, minimum items: 3, maximum items: 3, required	Location in a colorspace

representations

ColorRepresentations, required

Pre-calculcated visual representations of a color suitable for rendering

representations

RGB Array of number, minimum items: 3, maximum items: 3, required	RGB color array representing the axes r, g, and b in that order. Values are floats between 0 and 1.

inputs

InputsState, required

The state of all inputs during a given period is specified by a list of possible events combined with a boolean value indicating, if the given event occurred within the period.

inputs

// boolean, required	The boolean value indicates whether the named input event occurred during the last period.

detection

ColorMatchingResult, required

detection

matcher

any of UUID (string) or null, optional, Deprecated

Deprecated: use "chosen_matcher_id" instead

chosen_matcher_id

any of UUID (string) or null, required

unique identifier of the selected matcher

distances

Array of any of number or null, required

Distance between the sample's color position and the selected matcher's closest color position along the three axes of the color space.

The array contains three 'null' values, if no suitable matcher was found for the current color sample.

output_pattern

CurrentSwitchingOutputsState, required

output_pattern

states Array of any of boolean or null, required	List of True/False values describing the current states of the Switching Outputs

signal_level

number, required

The signal level indicates the usage of the internal ADC sampling range. This

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Retrieve all Matchers (color groups) ¶
GET /sensor/matchers Permission Scope sensor

Matchers (color groups) describe a color detection result. A Matcher contains details regarding the wanted behaviour of the Switching Outputs and a list of Detectables (color positions).

The most basic setup of a colorsensor could involve only a single color group containing all positive detection results. All samples that are not matched by this color group would indicate a problem of the monitored real-world process.

A more advanced usage of Matchers could additionally include a Matcher for the different acceptable background colors between real target objects (e.g. the color of the conveyor belt). Thus the Switching Outputs of the sensor could indicate whether a positive, a neutral or a negative real-world event was sampled.

Of course, every Matcher may also simply contain exactly one color position, in order to allow fine-grained classification of the target's appearance.

The tolerance field of a matcher describes the shape and the dimensions of the part of the colorspace that is covered by this matcher. Only color positions within this space may cause a for this matcher. A tolerance is specified by a shape and a dictionary of limits. Both attributes need to be specified. An empty dictionary of limits is interpreted as the default limits for the requested shape.

Request

Query Parameters

profile_id string, optional	Filter ColorMatchers by the given Detection Profile ID. Only ColorMatchers that are part of the given Detection Profile will be returned.

Response

Body

application/json

Properties (object)

data

object, required

data

matchers

Array of ColorMatcher, required

ColorMatcher[]

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

alias

Alias (integer), required, read-only

A numerical value that can be used to address an item in a collection. If an alias is specified alongside an uuid attribute, that alias can be used as an alternative to address the item in URLs and other protocols like Modbus or serial interfaces.

name

string, required

human-readable name of the matcher

tolerance

any of InfiniteColorTolerance, SphereColorTolerance, CylinderColorTolerance or BoxColorTolerance, required

Specification of a geometric shape and its dimensions in the current colorspaces.

InfiniteColorTolerance

limits object, required	limits
shape ToleranceShapeName (string), required	Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via `/api/sensor/capabilities`.

SphereColorTolerance

limits

object, required

limits

radius number, required

shape

ToleranceShapeName (string), required

Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via /api/sensor/capabilities.

CylinderColorTolerance

limits

object, required

limits

radius number, required
half_height number, required

shape

ToleranceShapeName (string), required

Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via /api/sensor/capabilities.

BoxColorTolerance

limits

object, required

limits

half_edges Array of number, minimum items: 3, maximum items: 3, required

shape

ToleranceShapeName (string), required

Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via /api/sensor/capabilities.

output_pattern

WantedSwitchingOutputsState, required

The combination of tristate values describes a logical state of the switching outputs of the sensor.

The states true or false cause the output to go up or down. The state null keeps the previous state of the output unchanged.

output_pattern

uuid UUID (string), pattern: `^[a-f0-9-]+$`, required, read-only	unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8
states Array of any of boolean or null, required	List of True/False/Null values describing the wanted states of the Switching Outputs

hold_time

HoldTime (number), maximum: 3153600000, required

Minimum duration (in seconds) of a matcher's output setup being applied after detection.

reset_output_after_hold_time_expired

boolean , default: false, required

Controls if the output should be reset after the hold time passed. This is helpful if you only sample by triggering inputs and wish to reset the outputs afterwards.

signal_color

any of string or null, required

A custom color name. How and what color will be displayed is defined by the client.

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Create a new Matcher (color group) ¶
POST /sensor/matchers Permission Scope sensor

Stores a new matcher (color group) on the sensor. In order to add colors to it, use the /api/sensor/detectables endpoint.

Request

Body

application/json

Properties (ColorMatcher)

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

alias

Alias (integer), required, read-only

name

string, required

human-readable name of the matcher

tolerance

any of InfiniteColorTolerance, SphereColorTolerance, CylinderColorTolerance or BoxColorTolerance, required

Specification of a geometric shape and its dimensions in the current colorspaces.

InfiniteColorTolerance

limits object, required	limits
shape ToleranceShapeName (string), required	Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via `/api/sensor/capabilities`.

SphereColorTolerance

limits

object, required

limits

radius number, required

shape

ToleranceShapeName (string), required

Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via /api/sensor/capabilities.

CylinderColorTolerance

limits

object, required

limits

radius number, required
half_height number, required

shape

ToleranceShapeName (string), required

Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via /api/sensor/capabilities.

BoxColorTolerance

limits

object, required

limits

half_edges Array of number, minimum items: 3, maximum items: 3, required

shape

ToleranceShapeName (string), required

Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via /api/sensor/capabilities.

output_pattern

WantedSwitchingOutputsState, required

The combination of tristate values describes a logical state of the switching outputs of the sensor.

The states true or false cause the output to go up or down. The state null keeps the previous state of the output unchanged.

output_pattern

uuid UUID (string), pattern: `^[a-f0-9-]+$`, required, read-only	unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8
states Array of any of boolean or null, required	List of True/False/Null values describing the wanted states of the Switching Outputs

hold_time

HoldTime (number), maximum: 3153600000, required

Minimum duration (in seconds) of a matcher's output setup being applied after detection.

reset_output_after_hold_time_expired

boolean , default: false, required

Controls if the output should be reset after the hold time passed. This is helpful if you only sample by triggering inputs and wish to reset the outputs afterwards.

signal_color

any of string or null, required

A custom color name. How and what color will be displayed is defined by the client.

Example

{
  "uuid": "9ffaa31f-8011-44f5-bb2a-f91e4be50764",
  "alias": 6,
  "name": "clean bottle cap",
  "tolerance": {
    "limits": {
      "radius": 2,
      "half_height": 4
    },
    "shape": "cylinder"
  },
  "output_pattern": {
    "uuid": "1adc74e2-96ac-4761-b9e6-2d93e02d9244",
    "states": [
      true,
      false,
      false
    ]
  },
  "hold_time": 0,
  "reset_output_after_hold_time_expired": false,
  "signal_color": null
}

Response

Body

application/json

Properties (object)

data

ColorMatcher, required

A matcher represents a distinguished detection result and the wanted behaviour of the sensor whenever it is encountered.

ColorMatcher

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

alias

Alias (integer), required, read-only

name

string, required

human-readable name of the matcher

tolerance

any of InfiniteColorTolerance, SphereColorTolerance, CylinderColorTolerance or BoxColorTolerance, required

Specification of a geometric shape and its dimensions in the current colorspaces.

InfiniteColorTolerance

limits object, required	limits
shape ToleranceShapeName (string), required	Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via `/api/sensor/capabilities`.

SphereColorTolerance

limits

object, required

limits

radius number, required

shape

ToleranceShapeName (string), required

Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via /api/sensor/capabilities.

CylinderColorTolerance

limits

object, required

limits

radius number, required
half_height number, required

shape

ToleranceShapeName (string), required

Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via /api/sensor/capabilities.

BoxColorTolerance

limits

object, required

limits

half_edges Array of number, minimum items: 3, maximum items: 3, required

shape

ToleranceShapeName (string), required

Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via /api/sensor/capabilities.

output_pattern

WantedSwitchingOutputsState, required

The combination of tristate values describes a logical state of the switching outputs of the sensor.

The states true or false cause the output to go up or down. The state null keeps the previous state of the output unchanged.

output_pattern

uuid UUID (string), pattern: `^[a-f0-9-]+$`, required, read-only	unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8
states Array of any of boolean or null, required	List of True/False/Null values describing the wanted states of the Switching Outputs

hold_time

HoldTime (number), maximum: 3153600000, required

Minimum duration (in seconds) of a matcher's output setup being applied after detection.

reset_output_after_hold_time_expired

boolean , default: false, required

Controls if the output should be reset after the hold time passed. This is helpful if you only sample by triggering inputs and wish to reset the outputs afterwards.

signal_color

any of string or null, required

A custom color name. How and what color will be displayed is defined by the client.

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.validation.collection_size_exceeded

Input validation failed

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.validation.collection_size_exceeded

Remove multiple or all ColorMatchers ¶
DELETE /sensor/matchers Permission Scope sensor

Remove a selection of ColorMatchers either based on a given filter argument (if supported for this collection) or remove all ColorMatchers from the collection.

All delete requests result in an empty success response (204). This is even valid for a non-filtered DELETE request against an empty collection or for a filtered DELETE request against a collection without ColorMatchers matching the filter.

Response

The empty response indicates success

Retrieve Matcher (color group) Details ¶
GET /sensor/matchers/{itemId} Permission Scope sensor

Returns the current configuration of a matcher.

Request

Path Variables

itemId string, required

Response

Body

application/json

Properties (object)

data

ColorMatcher, required

A matcher represents a distinguished detection result and the wanted behaviour of the sensor whenever it is encountered.

ColorMatcher

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

alias

Alias (integer), required, read-only

name

string, required

human-readable name of the matcher

tolerance

any of InfiniteColorTolerance, SphereColorTolerance, CylinderColorTolerance or BoxColorTolerance, required

Specification of a geometric shape and its dimensions in the current colorspaces.

InfiniteColorTolerance

limits object, required	limits
shape ToleranceShapeName (string), required	Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via `/api/sensor/capabilities`.

SphereColorTolerance

limits

object, required

limits

radius number, required

shape

ToleranceShapeName (string), required

Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via /api/sensor/capabilities.

CylinderColorTolerance

limits

object, required

limits

radius number, required
half_height number, required

shape

ToleranceShapeName (string), required

Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via /api/sensor/capabilities.

BoxColorTolerance

limits

object, required

limits

half_edges Array of number, minimum items: 3, maximum items: 3, required

shape

ToleranceShapeName (string), required

Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via /api/sensor/capabilities.

output_pattern

WantedSwitchingOutputsState, required

The combination of tristate values describes a logical state of the switching outputs of the sensor.

The states true or false cause the output to go up or down. The state null keeps the previous state of the output unchanged.

output_pattern

uuid UUID (string), pattern: `^[a-f0-9-]+$`, required, read-only	unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8
states Array of any of boolean or null, required	List of True/False/Null values describing the wanted states of the Switching Outputs

hold_time

HoldTime (number), maximum: 3153600000, required

Minimum duration (in seconds) of a matcher's output setup being applied after detection.

reset_output_after_hold_time_expired

boolean , default: false, required

Controls if the output should be reset after the hold time passed. This is helpful if you only sample by triggering inputs and wish to reset the outputs afterwards.

signal_color

any of string or null, required

A custom color name. How and what color will be displayed is defined by the client.

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.not_found.collection.item

Delete a Matcher (color group) ¶
DELETE /sensor/matchers/{itemId} Permission Scope sensor

Deletes the matcher and all associated detectables.

Request

Path Variables

itemId string, required

Response

The empty response indicates success

May return the following error codes

LPLC.not_found.collection.item

Update the Matcher (color group) Configuration ¶
PUT /sensor/matchers/{itemId} Permission Scope sensor

Update the matcher with a new configuration.

Request

Path Variables

itemId string, required

Body

application/json

Properties (ColorMatcher)

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

alias

Alias (integer), required, read-only

name

string, required

human-readable name of the matcher

tolerance

any of InfiniteColorTolerance, SphereColorTolerance, CylinderColorTolerance or BoxColorTolerance, required

Specification of a geometric shape and its dimensions in the current colorspaces.

InfiniteColorTolerance

limits object, required	limits
shape ToleranceShapeName (string), required	Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via `/api/sensor/capabilities`.

SphereColorTolerance

limits

object, required

limits

radius number, required

shape

ToleranceShapeName (string), required

Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via /api/sensor/capabilities.

CylinderColorTolerance

limits

object, required

limits

radius number, required
half_height number, required

shape

ToleranceShapeName (string), required

Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via /api/sensor/capabilities.

BoxColorTolerance

limits

object, required

limits

half_edges Array of number, minimum items: 3, maximum items: 3, required

shape

ToleranceShapeName (string), required

Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via /api/sensor/capabilities.

output_pattern

WantedSwitchingOutputsState, required

The combination of tristate values describes a logical state of the switching outputs of the sensor.

The states true or false cause the output to go up or down. The state null keeps the previous state of the output unchanged.

output_pattern

uuid UUID (string), pattern: `^[a-f0-9-]+$`, required, read-only	unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8
states Array of any of boolean or null, required	List of True/False/Null values describing the wanted states of the Switching Outputs

hold_time

HoldTime (number), maximum: 3153600000, required

Minimum duration (in seconds) of a matcher's output setup being applied after detection.

reset_output_after_hold_time_expired

boolean , default: false, required

Controls if the output should be reset after the hold time passed. This is helpful if you only sample by triggering inputs and wish to reset the outputs afterwards.

signal_color

any of string or null, required

A custom color name. How and what color will be displayed is defined by the client.

Example

{
  "uuid": "9ffaa31f-8011-44f5-bb2a-f91e4be50764",
  "alias": 6,
  "name": "clean bottle cap",
  "tolerance": {
    "limits": {
      "radius": 2,
      "half_height": 4
    },
    "shape": "cylinder"
  },
  "output_pattern": {
    "uuid": "1adc74e2-96ac-4761-b9e6-2d93e02d9244",
    "states": [
      true,
      false,
      false
    ]
  },
  "hold_time": 0,
  "reset_output_after_hold_time_expired": false,
  "signal_color": null
}

Response

Body

application/json

Properties (object)

data

ColorMatcher, required

A matcher represents a distinguished detection result and the wanted behaviour of the sensor whenever it is encountered.

ColorMatcher

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

alias

Alias (integer), required, read-only

name

string, required

human-readable name of the matcher

tolerance

any of InfiniteColorTolerance, SphereColorTolerance, CylinderColorTolerance or BoxColorTolerance, required

Specification of a geometric shape and its dimensions in the current colorspaces.

InfiniteColorTolerance

limits object, required	limits
shape ToleranceShapeName (string), required	Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via `/api/sensor/capabilities`.

SphereColorTolerance

limits

object, required

limits

radius number, required

shape

ToleranceShapeName (string), required

Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via /api/sensor/capabilities.

CylinderColorTolerance

limits

object, required

limits

radius number, required
half_height number, required

shape

ToleranceShapeName (string), required

Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via /api/sensor/capabilities.

BoxColorTolerance

limits

object, required

limits

half_edges Array of number, minimum items: 3, maximum items: 3, required

shape

ToleranceShapeName (string), required

Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via /api/sensor/capabilities.

output_pattern

WantedSwitchingOutputsState, required

The combination of tristate values describes a logical state of the switching outputs of the sensor.

The states true or false cause the output to go up or down. The state null keeps the previous state of the output unchanged.

output_pattern

uuid UUID (string), pattern: `^[a-f0-9-]+$`, required, read-only	unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8
states Array of any of boolean or null, required	List of True/False/Null values describing the wanted states of the Switching Outputs

hold_time

HoldTime (number), maximum: 3153600000, required

Minimum duration (in seconds) of a matcher's output setup being applied after detection.

reset_output_after_hold_time_expired

boolean , default: false, required

Controls if the output should be reset after the hold time passed. This is helpful if you only sample by triggering inputs and wish to reset the outputs afterwards.

signal_color

any of string or null, required

A custom color name. How and what color will be displayed is defined by the client.

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.not_found.collection.item

Input validation failed

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.not_found.collection.item

Item not found

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.not_found.collection.item

Retrieve ColorDetectables ¶
GET /sensor/detectables Permission Scope sensor

Detectables describe positions in the currently selected colorspace. Each detectable is part of a Matcher. Every Matcher may contain zero or more Detectables.

Detectables are used to determine the most suitable Matcher for a sampled color. This closest match defines the result of a sampling period and thus the behaviour of the sensor during the next sampling period.

Request

Query Parameters

matcher_id UUID (string), pattern: `^[a-f0-9-]+$`, optional, read-only	Filter detectables by the given Matcher ID. Only Detectables that are part of the given Matcher will be returned.
profile_id string, optional	Filter ColorDetectables by the given Detection Profile ID. Only ColorDetectables that are part of the given Detection Profile will be returned.

Response

Body

application/json

Properties (object)

data

object, required

data

detectables

Array of ColorDetectable, required

ColorDetectable[]

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

alias

Alias (integer), required, read-only

matcher_id

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

reference to the Matcher containing this Detectable

color

TransformedColor, required

A color represented by a coordinate in the colorspace. The array indices of the values property match the order of the colorspace.axes property of currently used detection profile.

color

values Array of number, minimum items: 3, maximum items: 3, required	Location in a colorspace

representations

ColorRepresentations, optional, read-only

Pre-calculcated visual representations of a color suitable for rendering

representations

RGB Array of number, minimum items: 3, maximum items: 3, required	RGB color array representing the axes r, g, and b in that order. Values are floats between 0 and 1.

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Remove multiple or all ColorDetectables ¶
DELETE /sensor/detectables Permission Scope sensor

Remove a selection of ColorDetectables either based on a given filter argument (if supported for this collection) or remove all ColorDetectables from the collection.

Request

Query Parameters

matcher_id UUID (string), pattern: `^[a-f0-9-]+$`, optional, read-only	Remove only detectables with the given Matcher ID.
profile_id string, optional	Filter ColorDetectables by the given Detection Profile ID. Only ColorDetectables that are part of the given Detection Profile will be returned.

Response

The empty response indicates success

Create ColorDetectables ¶
POST /sensor/detectables Permission Scope sensor

Create a new ColorDetectable

All supported data attributes in the body of the request are optional.

Request

Body

application/json

Properties (ColorDetectable)

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

alias

Alias (integer), required, read-only

matcher_id

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

reference to the Matcher containing this Detectable

color

TransformedColor, required

A color represented by a coordinate in the colorspace. The array indices of the values property match the order of the colorspace.axes property of currently used detection profile.

color

values Array of number, minimum items: 3, maximum items: 3, required	Location in a colorspace

representations

ColorRepresentations, optional, read-only

Pre-calculcated visual representations of a color suitable for rendering

representations

RGB Array of number, minimum items: 3, maximum items: 3, required	RGB color array representing the axes r, g, and b in that order. Values are floats between 0 and 1.

Example

{
  "uuid": "9f968e8a-ad9c-45ce-9beb-a55011856a99",
  "alias": 2,
  "matcher_id": "1c7e9725-8753-4b6c-a0b7-a71d7e915cb5",
  "color": {
    "values": [
      0.476731,
      0.381263,
      0.128475
    ]
  },
  "representations": {
    "RGB": [
      0.396114,
      0.479113,
      0.552308
    ]
  }
}

Response

Body

application/json

Properties (object)

data

ColorDetectable, required

A detectable represents the numeric position in a colorspace. It is connected to a Matcher.

ColorDetectable

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

alias

Alias (integer), required, read-only

matcher_id

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

reference to the Matcher containing this Detectable

color

TransformedColor, required

A color represented by a coordinate in the colorspace. The array indices of the values property match the order of the colorspace.axes property of currently used detection profile.

color

values Array of number, minimum items: 3, maximum items: 3, required	Location in a colorspace

representations

ColorRepresentations, optional, read-only

Pre-calculcated visual representations of a color suitable for rendering

representations

RGB Array of number, minimum items: 3, maximum items: 3, required	RGB color array representing the axes r, g, and b in that order. Values are floats between 0 and 1.

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.validation.collection_size_exceeded

Input validation failed

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.validation.collection_size_exceeded

Delete ColorDetectable ¶
DELETE /sensor/detectables/{itemId} Permission Scope sensor

Deletes a single ColorDetectable

Request

Path Variables

itemId string, required

Response

The empty response indicates success

May return the following error codes

LCOL.samples.unavailable

Modify ColorDetectable ¶
PUT /sensor/detectables/{itemId} Permission Scope sensor

Modifies a single ColorDetectable

Request

Path Variables

itemId string, required

Body

application/json

Properties (ColorDetectable)

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

alias

Alias (integer), required, read-only

matcher_id

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

reference to the Matcher containing this Detectable

color

TransformedColor, required

A color represented by a coordinate in the colorspace. The array indices of the values property match the order of the colorspace.axes property of currently used detection profile.

color

values Array of number, minimum items: 3, maximum items: 3, required	Location in a colorspace

representations

ColorRepresentations, optional, read-only

Pre-calculcated visual representations of a color suitable for rendering

representations

RGB Array of number, minimum items: 3, maximum items: 3, required	RGB color array representing the axes r, g, and b in that order. Values are floats between 0 and 1.

Example

{
  "uuid": "9f968e8a-ad9c-45ce-9beb-a55011856a99",
  "alias": 2,
  "matcher_id": "1c7e9725-8753-4b6c-a0b7-a71d7e915cb5",
  "color": {
    "values": [
      0.476731,
      0.381263,
      0.128475
    ]
  },
  "representations": {
    "RGB": [
      0.396114,
      0.479113,
      0.552308
    ]
  }
}

Response

Body

application/json

Properties (object)

data

ColorDetectable, required

A detectable represents the numeric position in a colorspace. It is connected to a Matcher.

ColorDetectable

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

alias

Alias (integer), required, read-only

matcher_id

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

reference to the Matcher containing this Detectable

color

TransformedColor, required

A color represented by a coordinate in the colorspace. The array indices of the values property match the order of the colorspace.axes property of currently used detection profile.

color

values Array of number, minimum items: 3, maximum items: 3, required	Location in a colorspace

representations

ColorRepresentations, optional, read-only

Pre-calculcated visual representations of a color suitable for rendering

representations

RGB Array of number, minimum items: 3, maximum items: 3, required	RGB color array representing the axes r, g, and b in that order. Values are floats between 0 and 1.

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LCOL.samples.unavailable

Input validation failed

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LCOL.samples.unavailable

Item not found

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LCOL.samples.unavailable

Get ColorDetectable ¶
GET /sensor/detectables/{itemId} Permission Scope sensor

Returns a single ColorDetectable

Request

Path Variables

itemId string, required

Response

Body

application/json

Properties (object)

data

ColorDetectable, required

A detectable represents the numeric position in a colorspace. It is connected to a Matcher.

ColorDetectable

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

alias

Alias (integer), required, read-only

matcher_id

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

reference to the Matcher containing this Detectable

color

TransformedColor, required

A color represented by a coordinate in the colorspace. The array indices of the values property match the order of the colorspace.axes property of currently used detection profile.

color

values Array of number, minimum items: 3, maximum items: 3, required	Location in a colorspace

representations

ColorRepresentations, optional, read-only

Pre-calculcated visual representations of a color suitable for rendering

representations

RGB Array of number, minimum items: 3, maximum items: 3, required	RGB color array representing the axes r, g, and b in that order. Values are floats between 0 and 1.

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LCOL.samples.unavailable

Switch current Detection Profile ¶
PUT /sensor/detection-profiles Permission Scope sensor

Only one of the available Detection Profiles is active at a given time. Write a new Detection Profile ID to the current_profile_id field in order to change the currently used profile.

Request

Body

application/json

Example
```
a014e415-0fec-4734-ac3f-30da0a5f3899
```

Response

Body

application/json

Properties (object)

data

CurrentDetectionProfileID (string), pattern: ^[a-f0-9-]+$, required, read-only

The sensor can store multiple Detection Profiles, but it can only apply one at a time. The field current_profile_id contains the UUID of the Detection Profile that is currently used by the sensor for its operation. It allows to use the shortcut API endpoint /api/sensor/detection-profiles/current instead of specifying a Detection Profile by its UUID.

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Create DetectionProfiles ¶
POST /sensor/detection-profiles Permission Scope sensor

Create a new DetectionProfile

All supported data attributes in the body of the request are optional.

Request

Body

application/json

Properties (DetectionProfile)

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

alias

Alias (integer), required, read-only

name

string, required

Human-readable name of the Detection Profile

colorspace

Colorspace, required

A colorspace describes the numeric conversion of colors under certain circumstances. Different standardized colorspaces are suitable for different detection tasks.

colorspace

name

string, required

space_id

ColorspaceID, required

Unique name of a colorspace

axes

Array of ColorspaceAxis, minimum items: 3, maximum items: 3, required

ColorspaceAxis[]

id string, required	Unique name
label string, required	Human-readable name
minimum number, required	lowest expected value of a color along this axis under usual circumstances
maximum number, required	highest expected value of a color along this axis under usual circumstances

non_matching_output

WantedSwitchingOutputsState, required

This state of the Switching Outputs is applied, if the currently sample color does not belong to any of the stored Matchers.

non_matching_output

uuid UUID (string), pattern: `^[a-f0-9-]+$`, required, read-only	unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8
states Array of any of boolean or null, required	List of True/False/Null values describing the wanted states of the Switching Outputs

non_matching_hold_time

HoldTime (number), maximum: 3153600000, required

Minimum duration (in seconds) of the non_matching_output state being applied to the Switching Outputs of the sensor. This prolonging of a potential non matching event may be useful, if the processing period of a connected actor exceeds the sampling period of the sensor.

compensation_settings

CompensationSettings, required

The compensation settings of a Detection Profile describe the configuration of internal sensor components related to the stabilization and compensation algorithms.

These values can be determined by issuing a POST request against /api/sensor/detection-profiles/current/autogain. The result is a suitable set of compensation settings for this sensor under the current circumstances.

The content of this data object is not meant to be manipulated by regular users. It should be handled as is (stored, transmitted and applied without modification or introspection).

compensation_settings

sampling_settings

SamplingSettings, required

Sampling Settings describe all details of the sampling process.

Its attributes may be queried and inspected (e.g. in order to retrieve the current sample rate).

Most values stored within the Sampling Settings should not be modified directly. The related API endpoint /api/sensor/detection-profiles/current/autogain should be used instead.

The only modifiable attributes within the Sampling Settings are the averages and the suppress_intermediate_averages value. It is safe to change both, even though the default value for averages calculated during an autogain operation should be optimal for most detection tasks.

sampling_settings

led_intensity number, minimum: 0, maximum: 1, required	relative intensity of the internal emitter during the light phase
base_sample_rate SampleRate (number), minimum: 0.01, required	The base sample rate determines the duration of a sampling period. After each sampling period, the gathered data is processed and a new detection result is calculated (e.g. the most suitable Matcher for the given sample). This may affect the state of the Switching Outputs or trigger configured actions. Thus the base sample rate defines the maximum rate of changes for the Switching Outputs. See also the effective sample rate.
effective_sample_rate SampleRate (number), minimum: 0.01, required	The effective sample rate is the numeric product of the base sample rate and the number of averages. It determines the minimum duration that a target needs to be sampled in order to determine its visual appearance correctly. With the default value of average set to one, this value is equal to the base sample rate.
minimum_wanted_sample_rate SampleRate (number), minimum: 0.01, required	This informational value represents the sample rate that was requested during the most recent Autogain operation. The effective sample rate may deviate from the wanted sample rate, if the requested sample rate was not achievable due to limitations of the sensor (e.g. exceeding the supported sample rate) or due to the environment (e.g. not enough light, thus a slower amplification with higher gain was necessary).
sample_light_phase boolean, required	defines if the sensor should periodically activate the internal emitter for sampling
sample_dark_phase boolean, required	defines if the sensor should periodically deactivate the internal emitter for sampling
averages AverageSampleCount (integer), minimum: 1, required	Number of previous samples to be averaged for every sampling result. A rolling averaging algorithm is applied to the samples.
suppress_intermediate_averages SuppressIntermediateAverages (boolean), required	If set to True, then only one sample is emitted after the configured number of averages is processed. Otherwise all intermdiate results are emitted, too. This toggles the behaviour between moving averaging and block-based averaging. Switching outputs are updated less frequently, if intermediate averages are suppressed.
amplification AmplificationLevel (integer), required	The amplification level specifies the internal configuration of an amplifier. This value is not meant to be manipulated by regular users. It should be handled as is (stored, transmitted and applied without modification or introspection).

white_reference

Array of number, required

The White Reference attribute is used for indicating a custom color balancing.

Its content is subject to internal use. Thus it should not be accessed directly, but only through the related API endpoints (e.g. /api/sensor/detection-profiles/{itemId}/white-reference).

normalization_constant

Array of number, required

Normalization constants are related to the White Reference.

Its content is subject to internal use. Thus it should not be accessed directly, but only through the related API endpoints (e.g. /api/sensor/detection-profiles/{itemId}/white-reference).

Example

{
  "name": "#0",
  "uuid": "2475df8d-85f0-4208-ba60-dce6cb282a96",
  "alias": 1,
  "non_matching_hold_time": 0,
  "colorspace": {
    "name": "L*a*b*",
    "axes": [
      {
        "id": "L",
        "label": "L*",
        "minimum": 0,
        "maximum": 100
      },
      {
        "id": "a",
        "label": "a*",
        "minimum": -500,
        "maximum": 500
      },
      {
        "id": "b",
        "label": "b*",
        "minimum": -200,
        "maximum": 200
      }
    ],
    "space_id": "Lab"
  },
  "compensation_settings": {
    "monitor_integration": {
      "control": 0.32499998807907104,
      "references": [
        0.7283520102500916,
        0.7442666888237,
        0.7066696286201477
      ]
    },
    "use_calibration_samples": true
  },
  "normalization_constant": [
    237.4935277662995,
    242.62655153828055,
    587.8264132734112
  ],
  "white_reference": [
    95.047,
    100,
    108.883
  ],
  "non_matching_output": {
    "uuid": "3f26aff4-8650-42a0-b319-51776c443fbc",
    "states": [
      true,
      true,
      true,
      true,
      true,
      true,
      true,
      true
    ]
  },
  "sampling_settings": {
    "led_intensity": 1,
    "amplification": 1,
    "sample_light_phase": true,
    "minimum_wanted_sample_rate": 1000,
    "averages": 1,
    "suppress_intermediate_averages": false,
    "base_sample_rate": 1000,
    "sample_dark_phase": true,
    "effective_sample_rate": 1000
  }
}

Response

Body

application/json

Properties (object)

data

DetectionProfile, required

A Detection Profile contains a complete set of sensor settings for a given detection task.

Multiple profiles can be stored in order to switch easily between different detection task or for the incremental development of a refined profile.

Some attributes of a Detection Profile expose internal details of the sensor, that should be determined indirectly via other means. These attributes are described only superficially, since they should be handled as is without changing their value or structure.

DetectionProfile

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

alias

Alias (integer), required, read-only

name

string, required

Human-readable name of the Detection Profile

colorspace

Colorspace, required

A colorspace describes the numeric conversion of colors under certain circumstances. Different standardized colorspaces are suitable for different detection tasks.

colorspace

name

string, required

space_id

ColorspaceID, required

Unique name of a colorspace

axes

Array of ColorspaceAxis, minimum items: 3, maximum items: 3, required

ColorspaceAxis[]

id string, required	Unique name
label string, required	Human-readable name
minimum number, required	lowest expected value of a color along this axis under usual circumstances
maximum number, required	highest expected value of a color along this axis under usual circumstances

non_matching_output

WantedSwitchingOutputsState, required

This state of the Switching Outputs is applied, if the currently sample color does not belong to any of the stored Matchers.

non_matching_output

uuid UUID (string), pattern: `^[a-f0-9-]+$`, required, read-only	unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8
states Array of any of boolean or null, required	List of True/False/Null values describing the wanted states of the Switching Outputs

non_matching_hold_time

HoldTime (number), maximum: 3153600000, required

compensation_settings

CompensationSettings, required

The compensation settings of a Detection Profile describe the configuration of internal sensor components related to the stabilization and compensation algorithms.

The content of this data object is not meant to be manipulated by regular users. It should be handled as is (stored, transmitted and applied without modification or introspection).

compensation_settings

sampling_settings

SamplingSettings, required

Sampling Settings describe all details of the sampling process.

Its attributes may be queried and inspected (e.g. in order to retrieve the current sample rate).

Most values stored within the Sampling Settings should not be modified directly. The related API endpoint /api/sensor/detection-profiles/current/autogain should be used instead.

sampling_settings

led_intensity number, minimum: 0, maximum: 1, required	relative intensity of the internal emitter during the light phase
base_sample_rate SampleRate (number), minimum: 0.01, required	The base sample rate determines the duration of a sampling period. After each sampling period, the gathered data is processed and a new detection result is calculated (e.g. the most suitable Matcher for the given sample). This may affect the state of the Switching Outputs or trigger configured actions. Thus the base sample rate defines the maximum rate of changes for the Switching Outputs. See also the effective sample rate.
effective_sample_rate SampleRate (number), minimum: 0.01, required	The effective sample rate is the numeric product of the base sample rate and the number of averages. It determines the minimum duration that a target needs to be sampled in order to determine its visual appearance correctly. With the default value of average set to one, this value is equal to the base sample rate.
minimum_wanted_sample_rate SampleRate (number), minimum: 0.01, required	This informational value represents the sample rate that was requested during the most recent Autogain operation. The effective sample rate may deviate from the wanted sample rate, if the requested sample rate was not achievable due to limitations of the sensor (e.g. exceeding the supported sample rate) or due to the environment (e.g. not enough light, thus a slower amplification with higher gain was necessary).
sample_light_phase boolean, required	defines if the sensor should periodically activate the internal emitter for sampling
sample_dark_phase boolean, required	defines if the sensor should periodically deactivate the internal emitter for sampling
averages AverageSampleCount (integer), minimum: 1, required	Number of previous samples to be averaged for every sampling result. A rolling averaging algorithm is applied to the samples.
suppress_intermediate_averages SuppressIntermediateAverages (boolean), required	If set to True, then only one sample is emitted after the configured number of averages is processed. Otherwise all intermdiate results are emitted, too. This toggles the behaviour between moving averaging and block-based averaging. Switching outputs are updated less frequently, if intermediate averages are suppressed.
amplification AmplificationLevel (integer), required	The amplification level specifies the internal configuration of an amplifier. This value is not meant to be manipulated by regular users. It should be handled as is (stored, transmitted and applied without modification or introspection).

white_reference

Array of number, required

The White Reference attribute is used for indicating a custom color balancing.

Its content is subject to internal use. Thus it should not be accessed directly, but only through the related API endpoints (e.g. /api/sensor/detection-profiles/{itemId}/white-reference).

normalization_constant

Array of number, required

Normalization constants are related to the White Reference.

Its content is subject to internal use. Thus it should not be accessed directly, but only through the related API endpoints (e.g. /api/sensor/detection-profiles/{itemId}/white-reference).

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.validation.collection_size_exceeded

Input validation failed

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.validation.collection_size_exceeded

Remove multiple or all DetectionProfiles ¶
DELETE /sensor/detection-profiles Permission Scope sensor

Remove a selection of DetectionProfiles either based on a given filter argument (if supported for this collection) or remove all DetectionProfiles from the collection.

Response

Body

application/json

Properties (object)

data

object, required

data

current_profile_id CurrentDetectionProfileID (string), pattern: `^[a-f0-9-]+$`, required, read-only	The sensor can store multiple Detection Profiles, but it can only apply one at a time. The field `current_profile_id` contains the UUID of the Detection Profile that is currently used by the sensor for its operation. It allows to use the shortcut API endpoint `/api/sensor/detection-profiles/current` instead of specifying a Detection Profile by its UUID.

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

The empty response indicates success

Retrieve DetectionProfiles ¶
GET /sensor/detection-profiles Permission Scope sensor

Retrieves a list of available DetectionProfiles

Response

Body

application/json

Properties (object)

data

object, required

data

detection-profiles

Array of DetectionProfile, required

DetectionProfile[]

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

alias

Alias (integer), required, read-only

name

string, required

Human-readable name of the Detection Profile

colorspace

Colorspace, required

A colorspace describes the numeric conversion of colors under certain circumstances. Different standardized colorspaces are suitable for different detection tasks.

colorspace

name

string, required

space_id

ColorspaceID, required

Unique name of a colorspace

axes

Array of ColorspaceAxis, minimum items: 3, maximum items: 3, required

ColorspaceAxis[]

id string, required	Unique name
label string, required	Human-readable name
minimum number, required	lowest expected value of a color along this axis under usual circumstances
maximum number, required	highest expected value of a color along this axis under usual circumstances

non_matching_output

WantedSwitchingOutputsState, required

This state of the Switching Outputs is applied, if the currently sample color does not belong to any of the stored Matchers.

non_matching_output

uuid UUID (string), pattern: `^[a-f0-9-]+$`, required, read-only	unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8
states Array of any of boolean or null, required	List of True/False/Null values describing the wanted states of the Switching Outputs

non_matching_hold_time

HoldTime (number), maximum: 3153600000, required

compensation_settings

CompensationSettings, required

The compensation settings of a Detection Profile describe the configuration of internal sensor components related to the stabilization and compensation algorithms.

The content of this data object is not meant to be manipulated by regular users. It should be handled as is (stored, transmitted and applied without modification or introspection).

compensation_settings

sampling_settings

SamplingSettings, required

Sampling Settings describe all details of the sampling process.

Its attributes may be queried and inspected (e.g. in order to retrieve the current sample rate).

Most values stored within the Sampling Settings should not be modified directly. The related API endpoint /api/sensor/detection-profiles/current/autogain should be used instead.

sampling_settings

led_intensity number, minimum: 0, maximum: 1, required	relative intensity of the internal emitter during the light phase
base_sample_rate SampleRate (number), minimum: 0.01, required	The base sample rate determines the duration of a sampling period. After each sampling period, the gathered data is processed and a new detection result is calculated (e.g. the most suitable Matcher for the given sample). This may affect the state of the Switching Outputs or trigger configured actions. Thus the base sample rate defines the maximum rate of changes for the Switching Outputs. See also the effective sample rate.
effective_sample_rate SampleRate (number), minimum: 0.01, required	The effective sample rate is the numeric product of the base sample rate and the number of averages. It determines the minimum duration that a target needs to be sampled in order to determine its visual appearance correctly. With the default value of average set to one, this value is equal to the base sample rate.
minimum_wanted_sample_rate SampleRate (number), minimum: 0.01, required	This informational value represents the sample rate that was requested during the most recent Autogain operation. The effective sample rate may deviate from the wanted sample rate, if the requested sample rate was not achievable due to limitations of the sensor (e.g. exceeding the supported sample rate) or due to the environment (e.g. not enough light, thus a slower amplification with higher gain was necessary).
sample_light_phase boolean, required	defines if the sensor should periodically activate the internal emitter for sampling
sample_dark_phase boolean, required	defines if the sensor should periodically deactivate the internal emitter for sampling
averages AverageSampleCount (integer), minimum: 1, required	Number of previous samples to be averaged for every sampling result. A rolling averaging algorithm is applied to the samples.
suppress_intermediate_averages SuppressIntermediateAverages (boolean), required	If set to True, then only one sample is emitted after the configured number of averages is processed. Otherwise all intermdiate results are emitted, too. This toggles the behaviour between moving averaging and block-based averaging. Switching outputs are updated less frequently, if intermediate averages are suppressed.
amplification AmplificationLevel (integer), required	The amplification level specifies the internal configuration of an amplifier. This value is not meant to be manipulated by regular users. It should be handled as is (stored, transmitted and applied without modification or introspection).

white_reference

Array of number, required

The White Reference attribute is used for indicating a custom color balancing.

Its content is subject to internal use. Thus it should not be accessed directly, but only through the related API endpoints (e.g. /api/sensor/detection-profiles/{itemId}/white-reference).

normalization_constant

Array of number, required

Normalization constants are related to the White Reference.

Its content is subject to internal use. Thus it should not be accessed directly, but only through the related API endpoints (e.g. /api/sensor/detection-profiles/{itemId}/white-reference).

current_profile_id

CurrentDetectionProfileID (string), pattern: ^[a-f0-9-]+$, required, read-only

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Delete DetectionProfile ¶
DELETE /sensor/detection-profiles/{itemId} Permission Scope sensor

Deletes a single DetectionProfile

Request

Path Variables

itemId string, required

Response

The empty response indicates success

May return the following error codes

LPLC.not_found.collection.item

Modify DetectionProfile ¶
PUT /sensor/detection-profiles/{itemId} Permission Scope sensor

Modifies a single DetectionProfile

Request

Path Variables

itemId string, required

Body

application/json

Properties (DetectionProfile)

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

alias

Alias (integer), required, read-only

name

string, required

Human-readable name of the Detection Profile

colorspace

Colorspace, required

A colorspace describes the numeric conversion of colors under certain circumstances. Different standardized colorspaces are suitable for different detection tasks.

colorspace

name

string, required

space_id

ColorspaceID, required

Unique name of a colorspace

axes

Array of ColorspaceAxis, minimum items: 3, maximum items: 3, required

ColorspaceAxis[]

id string, required	Unique name
label string, required	Human-readable name
minimum number, required	lowest expected value of a color along this axis under usual circumstances
maximum number, required	highest expected value of a color along this axis under usual circumstances

non_matching_output

WantedSwitchingOutputsState, required

This state of the Switching Outputs is applied, if the currently sample color does not belong to any of the stored Matchers.

non_matching_output

uuid UUID (string), pattern: `^[a-f0-9-]+$`, required, read-only	unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8
states Array of any of boolean or null, required	List of True/False/Null values describing the wanted states of the Switching Outputs

non_matching_hold_time

HoldTime (number), maximum: 3153600000, required

compensation_settings

CompensationSettings, required

The compensation settings of a Detection Profile describe the configuration of internal sensor components related to the stabilization and compensation algorithms.

The content of this data object is not meant to be manipulated by regular users. It should be handled as is (stored, transmitted and applied without modification or introspection).

compensation_settings

sampling_settings

SamplingSettings, required

Sampling Settings describe all details of the sampling process.

Its attributes may be queried and inspected (e.g. in order to retrieve the current sample rate).

Most values stored within the Sampling Settings should not be modified directly. The related API endpoint /api/sensor/detection-profiles/current/autogain should be used instead.

sampling_settings

led_intensity number, minimum: 0, maximum: 1, required	relative intensity of the internal emitter during the light phase
base_sample_rate SampleRate (number), minimum: 0.01, required	The base sample rate determines the duration of a sampling period. After each sampling period, the gathered data is processed and a new detection result is calculated (e.g. the most suitable Matcher for the given sample). This may affect the state of the Switching Outputs or trigger configured actions. Thus the base sample rate defines the maximum rate of changes for the Switching Outputs. See also the effective sample rate.
effective_sample_rate SampleRate (number), minimum: 0.01, required	The effective sample rate is the numeric product of the base sample rate and the number of averages. It determines the minimum duration that a target needs to be sampled in order to determine its visual appearance correctly. With the default value of average set to one, this value is equal to the base sample rate.
minimum_wanted_sample_rate SampleRate (number), minimum: 0.01, required	This informational value represents the sample rate that was requested during the most recent Autogain operation. The effective sample rate may deviate from the wanted sample rate, if the requested sample rate was not achievable due to limitations of the sensor (e.g. exceeding the supported sample rate) or due to the environment (e.g. not enough light, thus a slower amplification with higher gain was necessary).
sample_light_phase boolean, required	defines if the sensor should periodically activate the internal emitter for sampling
sample_dark_phase boolean, required	defines if the sensor should periodically deactivate the internal emitter for sampling
averages AverageSampleCount (integer), minimum: 1, required	Number of previous samples to be averaged for every sampling result. A rolling averaging algorithm is applied to the samples.
suppress_intermediate_averages SuppressIntermediateAverages (boolean), required	If set to True, then only one sample is emitted after the configured number of averages is processed. Otherwise all intermdiate results are emitted, too. This toggles the behaviour between moving averaging and block-based averaging. Switching outputs are updated less frequently, if intermediate averages are suppressed.
amplification AmplificationLevel (integer), required	The amplification level specifies the internal configuration of an amplifier. This value is not meant to be manipulated by regular users. It should be handled as is (stored, transmitted and applied without modification or introspection).

white_reference

Array of number, required

The White Reference attribute is used for indicating a custom color balancing.

Its content is subject to internal use. Thus it should not be accessed directly, but only through the related API endpoints (e.g. /api/sensor/detection-profiles/{itemId}/white-reference).

normalization_constant

Array of number, required

Normalization constants are related to the White Reference.

Its content is subject to internal use. Thus it should not be accessed directly, but only through the related API endpoints (e.g. /api/sensor/detection-profiles/{itemId}/white-reference).

Example

{
  "name": "#0",
  "uuid": "2475df8d-85f0-4208-ba60-dce6cb282a96",
  "alias": 1,
  "non_matching_hold_time": 0,
  "colorspace": {
    "name": "L*a*b*",
    "axes": [
      {
        "id": "L",
        "label": "L*",
        "minimum": 0,
        "maximum": 100
      },
      {
        "id": "a",
        "label": "a*",
        "minimum": -500,
        "maximum": 500
      },
      {
        "id": "b",
        "label": "b*",
        "minimum": -200,
        "maximum": 200
      }
    ],
    "space_id": "Lab"
  },
  "compensation_settings": {
    "monitor_integration": {
      "control": 0.32499998807907104,
      "references": [
        0.7283520102500916,
        0.7442666888237,
        0.7066696286201477
      ]
    },
    "use_calibration_samples": true
  },
  "normalization_constant": [
    237.4935277662995,
    242.62655153828055,
    587.8264132734112
  ],
  "white_reference": [
    95.047,
    100,
    108.883
  ],
  "non_matching_output": {
    "uuid": "3f26aff4-8650-42a0-b319-51776c443fbc",
    "states": [
      true,
      true,
      true,
      true,
      true,
      true,
      true,
      true
    ]
  },
  "sampling_settings": {
    "led_intensity": 1,
    "amplification": 1,
    "sample_light_phase": true,
    "minimum_wanted_sample_rate": 1000,
    "averages": 1,
    "suppress_intermediate_averages": false,
    "base_sample_rate": 1000,
    "sample_dark_phase": true,
    "effective_sample_rate": 1000
  }
}

Response

Body

application/json

Properties (object)

data

DetectionProfile, required

A Detection Profile contains a complete set of sensor settings for a given detection task.

Multiple profiles can be stored in order to switch easily between different detection task or for the incremental development of a refined profile.

DetectionProfile

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

alias

Alias (integer), required, read-only

name

string, required

Human-readable name of the Detection Profile

colorspace

Colorspace, required

A colorspace describes the numeric conversion of colors under certain circumstances. Different standardized colorspaces are suitable for different detection tasks.

colorspace

name

string, required

space_id

ColorspaceID, required

Unique name of a colorspace

axes

Array of ColorspaceAxis, minimum items: 3, maximum items: 3, required

ColorspaceAxis[]

id string, required	Unique name
label string, required	Human-readable name
minimum number, required	lowest expected value of a color along this axis under usual circumstances
maximum number, required	highest expected value of a color along this axis under usual circumstances

non_matching_output

WantedSwitchingOutputsState, required

This state of the Switching Outputs is applied, if the currently sample color does not belong to any of the stored Matchers.

non_matching_output

uuid UUID (string), pattern: `^[a-f0-9-]+$`, required, read-only	unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8
states Array of any of boolean or null, required	List of True/False/Null values describing the wanted states of the Switching Outputs

non_matching_hold_time

HoldTime (number), maximum: 3153600000, required

compensation_settings

CompensationSettings, required

The compensation settings of a Detection Profile describe the configuration of internal sensor components related to the stabilization and compensation algorithms.

The content of this data object is not meant to be manipulated by regular users. It should be handled as is (stored, transmitted and applied without modification or introspection).

compensation_settings

sampling_settings

SamplingSettings, required

Sampling Settings describe all details of the sampling process.

Its attributes may be queried and inspected (e.g. in order to retrieve the current sample rate).

Most values stored within the Sampling Settings should not be modified directly. The related API endpoint /api/sensor/detection-profiles/current/autogain should be used instead.

sampling_settings

led_intensity number, minimum: 0, maximum: 1, required	relative intensity of the internal emitter during the light phase
base_sample_rate SampleRate (number), minimum: 0.01, required	The base sample rate determines the duration of a sampling period. After each sampling period, the gathered data is processed and a new detection result is calculated (e.g. the most suitable Matcher for the given sample). This may affect the state of the Switching Outputs or trigger configured actions. Thus the base sample rate defines the maximum rate of changes for the Switching Outputs. See also the effective sample rate.
effective_sample_rate SampleRate (number), minimum: 0.01, required	The effective sample rate is the numeric product of the base sample rate and the number of averages. It determines the minimum duration that a target needs to be sampled in order to determine its visual appearance correctly. With the default value of average set to one, this value is equal to the base sample rate.
minimum_wanted_sample_rate SampleRate (number), minimum: 0.01, required	This informational value represents the sample rate that was requested during the most recent Autogain operation. The effective sample rate may deviate from the wanted sample rate, if the requested sample rate was not achievable due to limitations of the sensor (e.g. exceeding the supported sample rate) or due to the environment (e.g. not enough light, thus a slower amplification with higher gain was necessary).
sample_light_phase boolean, required	defines if the sensor should periodically activate the internal emitter for sampling
sample_dark_phase boolean, required	defines if the sensor should periodically deactivate the internal emitter for sampling
averages AverageSampleCount (integer), minimum: 1, required	Number of previous samples to be averaged for every sampling result. A rolling averaging algorithm is applied to the samples.
suppress_intermediate_averages SuppressIntermediateAverages (boolean), required	If set to True, then only one sample is emitted after the configured number of averages is processed. Otherwise all intermdiate results are emitted, too. This toggles the behaviour between moving averaging and block-based averaging. Switching outputs are updated less frequently, if intermediate averages are suppressed.
amplification AmplificationLevel (integer), required	The amplification level specifies the internal configuration of an amplifier. This value is not meant to be manipulated by regular users. It should be handled as is (stored, transmitted and applied without modification or introspection).

white_reference

Array of number, required

The White Reference attribute is used for indicating a custom color balancing.

Its content is subject to internal use. Thus it should not be accessed directly, but only through the related API endpoints (e.g. /api/sensor/detection-profiles/{itemId}/white-reference).

normalization_constant

Array of number, required

Normalization constants are related to the White Reference.

Its content is subject to internal use. Thus it should not be accessed directly, but only through the related API endpoints (e.g. /api/sensor/detection-profiles/{itemId}/white-reference).

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.not_found.collection.item

Input validation failed

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.not_found.collection.item

Item not found

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.not_found.collection.item

Get DetectionProfile ¶
GET /sensor/detection-profiles/{itemId} Permission Scope sensor

Returns a single DetectionProfile

Request

Path Variables

itemId string, required

Response

Body

application/json

Properties (object)

data

DetectionProfile, required

A Detection Profile contains a complete set of sensor settings for a given detection task.

Multiple profiles can be stored in order to switch easily between different detection task or for the incremental development of a refined profile.

DetectionProfile

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

alias

Alias (integer), required, read-only

name

string, required

Human-readable name of the Detection Profile

colorspace

Colorspace, required

A colorspace describes the numeric conversion of colors under certain circumstances. Different standardized colorspaces are suitable for different detection tasks.

colorspace

name

string, required

space_id

ColorspaceID, required

Unique name of a colorspace

axes

Array of ColorspaceAxis, minimum items: 3, maximum items: 3, required

ColorspaceAxis[]

id string, required	Unique name
label string, required	Human-readable name
minimum number, required	lowest expected value of a color along this axis under usual circumstances
maximum number, required	highest expected value of a color along this axis under usual circumstances

non_matching_output

WantedSwitchingOutputsState, required

This state of the Switching Outputs is applied, if the currently sample color does not belong to any of the stored Matchers.

non_matching_output

uuid UUID (string), pattern: `^[a-f0-9-]+$`, required, read-only	unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8
states Array of any of boolean or null, required	List of True/False/Null values describing the wanted states of the Switching Outputs

non_matching_hold_time

HoldTime (number), maximum: 3153600000, required

compensation_settings

CompensationSettings, required

The compensation settings of a Detection Profile describe the configuration of internal sensor components related to the stabilization and compensation algorithms.

The content of this data object is not meant to be manipulated by regular users. It should be handled as is (stored, transmitted and applied without modification or introspection).

compensation_settings

sampling_settings

SamplingSettings, required

Sampling Settings describe all details of the sampling process.

Its attributes may be queried and inspected (e.g. in order to retrieve the current sample rate).

Most values stored within the Sampling Settings should not be modified directly. The related API endpoint /api/sensor/detection-profiles/current/autogain should be used instead.

sampling_settings

led_intensity number, minimum: 0, maximum: 1, required	relative intensity of the internal emitter during the light phase
base_sample_rate SampleRate (number), minimum: 0.01, required	The base sample rate determines the duration of a sampling period. After each sampling period, the gathered data is processed and a new detection result is calculated (e.g. the most suitable Matcher for the given sample). This may affect the state of the Switching Outputs or trigger configured actions. Thus the base sample rate defines the maximum rate of changes for the Switching Outputs. See also the effective sample rate.
effective_sample_rate SampleRate (number), minimum: 0.01, required	The effective sample rate is the numeric product of the base sample rate and the number of averages. It determines the minimum duration that a target needs to be sampled in order to determine its visual appearance correctly. With the default value of average set to one, this value is equal to the base sample rate.
minimum_wanted_sample_rate SampleRate (number), minimum: 0.01, required	This informational value represents the sample rate that was requested during the most recent Autogain operation. The effective sample rate may deviate from the wanted sample rate, if the requested sample rate was not achievable due to limitations of the sensor (e.g. exceeding the supported sample rate) or due to the environment (e.g. not enough light, thus a slower amplification with higher gain was necessary).
sample_light_phase boolean, required	defines if the sensor should periodically activate the internal emitter for sampling
sample_dark_phase boolean, required	defines if the sensor should periodically deactivate the internal emitter for sampling
averages AverageSampleCount (integer), minimum: 1, required	Number of previous samples to be averaged for every sampling result. A rolling averaging algorithm is applied to the samples.
suppress_intermediate_averages SuppressIntermediateAverages (boolean), required	If set to True, then only one sample is emitted after the configured number of averages is processed. Otherwise all intermdiate results are emitted, too. This toggles the behaviour between moving averaging and block-based averaging. Switching outputs are updated less frequently, if intermediate averages are suppressed.
amplification AmplificationLevel (integer), required	The amplification level specifies the internal configuration of an amplifier. This value is not meant to be manipulated by regular users. It should be handled as is (stored, transmitted and applied without modification or introspection).

white_reference

Array of number, required

The White Reference attribute is used for indicating a custom color balancing.

Its content is subject to internal use. Thus it should not be accessed directly, but only through the related API endpoints (e.g. /api/sensor/detection-profiles/{itemId}/white-reference).

normalization_constant

Array of number, required

Normalization constants are related to the White Reference.

Its content is subject to internal use. Thus it should not be accessed directly, but only through the related API endpoints (e.g. /api/sensor/detection-profiles/{itemId}/white-reference).

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.not_found.collection.item

Start Autogain Procedure ¶
POST /sensor/detection-profiles/{itemId}/autogain Permission Scope sensor

Execute the autogain procedure in order to determine suitable sampling properties for the current environment. The resulting sampling setup is applied automatically. These new settings are in effect as soon as the response is sent.

The autogain procedure initiates a dynamic recalibration of the internal emitter and all compensation processes. It results in quick changes or flashing of the internal emitter (if enabled). The operation is usually finished within 15 seconds. The response is sent after all related activities are completed. Later requests for a sample will return values based on the adjusted sampling settings.

Request

Path Variables

itemId string, required

Body

application/json

Properties (AutogainSettings)

level number , default: `0.8`, minimum: 0.01, maximum: 1, optional	Target value for the auto-gain procedure
minimum_sample_rate SampleRate (number), minimum: 0.01, optional	Desired sample rate (the default is the current sample rate)
enable_internal_emitter boolean , default: `true`, optional	controls the power of the internal light source
enable_ambient_light_compensation boolean , default: `true`, optional	Control the ambient light compensation procedure. This setting is only relevant if `enable_internal_emitter` is set to true. The ambient light compensation leads to a pulsed usage of the internal light emitter. Samples are collected for alternating light and dark phases. This allows to calculate a color sample of the target excluding any optical interference from external light sources. You should not disable ambient light compensation unless the optical path is perfectly isolated. Otherwise external light will inevitably interfere with the color sampling.
averages AverageSampleCount (integer), minimum: 1, optional	Number of previous samples to be averaged for every sampling result. A rolling averaging algorithm is applied to the samples.

Example

{
  "level": 0.7,
  "minimum_sample_rate": 1500,
  "enable_internal_emitter": true,
  "enable_ambient_light_compensation": true
}

Response

Body

application/json

Properties (object)

data

object, required

data

sampling_settings

SamplingSettings, required

Sampling Settings describe all details of the sampling process.

Its attributes may be queried and inspected (e.g. in order to retrieve the current sample rate).

Most values stored within the Sampling Settings should not be modified directly. The related API endpoint /api/sensor/detection-profiles/current/autogain should be used instead.

SamplingSettings

led_intensity number, minimum: 0, maximum: 1, required	relative intensity of the internal emitter during the light phase
base_sample_rate SampleRate (number), minimum: 0.01, required	The base sample rate determines the duration of a sampling period. After each sampling period, the gathered data is processed and a new detection result is calculated (e.g. the most suitable Matcher for the given sample). This may affect the state of the Switching Outputs or trigger configured actions. Thus the base sample rate defines the maximum rate of changes for the Switching Outputs. See also the effective sample rate.
effective_sample_rate SampleRate (number), minimum: 0.01, required	The effective sample rate is the numeric product of the base sample rate and the number of averages. It determines the minimum duration that a target needs to be sampled in order to determine its visual appearance correctly. With the default value of average set to one, this value is equal to the base sample rate.
minimum_wanted_sample_rate SampleRate (number), minimum: 0.01, required	This informational value represents the sample rate that was requested during the most recent Autogain operation. The effective sample rate may deviate from the wanted sample rate, if the requested sample rate was not achievable due to limitations of the sensor (e.g. exceeding the supported sample rate) or due to the environment (e.g. not enough light, thus a slower amplification with higher gain was necessary).
sample_light_phase boolean, required	defines if the sensor should periodically activate the internal emitter for sampling
sample_dark_phase boolean, required	defines if the sensor should periodically deactivate the internal emitter for sampling
averages AverageSampleCount (integer), minimum: 1, required	Number of previous samples to be averaged for every sampling result. A rolling averaging algorithm is applied to the samples.
suppress_intermediate_averages SuppressIntermediateAverages (boolean), required	If set to True, then only one sample is emitted after the configured number of averages is processed. Otherwise all intermdiate results are emitted, too. This toggles the behaviour between moving averaging and block-based averaging. Switching outputs are updated less frequently, if intermediate averages are suppressed.
amplification AmplificationLevel (integer), required	The amplification level specifies the internal configuration of an amplifier. This value is not meant to be manipulated by regular users. It should be handled as is (stored, transmitted and applied without modification or introspection).

compensation_settings

CompensationSettings, required

The compensation settings of a Detection Profile describe the configuration of internal sensor components related to the stabilization and compensation algorithms.

The content of this data object is not meant to be manipulated by regular users. It should be handled as is (stored, transmitted and applied without modification or introspection).

CompensationSettings

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LCOL.autogain
LCOL.autogain.invalid_target_level
LCOL.autogain.invalid_sample_rate
LPLC.validation.boolean

The Autogain procedure may fail due to invalid input data or in case of unmet preconditions (e.g. the target is too dark).

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LCOL.autogain
LCOL.autogain.invalid_target_level
LCOL.autogain.invalid_sample_rate
LPLC.validation.boolean

Query custom White Reference ¶
GET /sensor/detection-profiles/{itemId}/white-reference Permission Scope sensor

Verify the existence of a custom White Reference. A successful response (HTTP Status 200) indicates that a custom White Reference is in use. The not found response (HTTP Status 404) indicates that the factory default White Reference is used instead.

The detailed content of the response is not relevant. Instead the related normalization_constants field of the Detection Profile is adjusted based on the current White Reference.

Request

Path Variables

itemId string, required

Response

A custom White Reference is in use.

Body

application/json

Properties (object)

data

Array of number, required

The White Reference attribute is used for indicating a custom color balancing.

Its content is subject to internal use. Thus it should not be accessed directly, but only through the related API endpoints (e.g. /api/sensor/detection-profiles/{itemId}/white-reference).

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

The factory default White Reference is in use.

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Sample a custom White Reference ¶
POST /sensor/detection-profiles/{itemId}/white-reference Permission Scope sensor

Apply a custom White Reference for the color handling of the sensor. The currently sampled color is used for calculating the White Reference. You should pick a neutral white target for this action.

Please note that the change of the White Reference is not in effect immediately. Thus you should wait for three seconds, before sampling new values.

Request

Path Variables

itemId string, required

Response

Body

application/json

Properties (object)

data

Array of number, required

The White Reference attribute is used for indicating a custom color balancing.

Its content is subject to internal use. Thus it should not be accessed directly, but only through the related API endpoints (e.g. /api/sensor/detection-profiles/{itemId}/white-reference).

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LCOL.white_reference.too_dark

The current visual target is not suitable for the calculation of the White Reference. Probably it is too dark.

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LCOL.white_reference.too_dark

Reset White Reference to factory default ¶
DELETE /sensor/detection-profiles/{itemId}/white-reference Permission Scope sensor

Remove a previously sampled custom White Reference.

Request

Path Variables

itemId string, required

Response

The custom White Reference was removed.

No custom White Reference was sampled before (i.e. the factory defaults are used).

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Retrieve ActionTriggers ¶
GET /sensor/action-triggers Permission Scope sensor

The sensor can be programmed to react on specific external or internal events. The available actions can be either triggered via trigger input lines or via API requests. This allows customized behaviour, e.g. teaching colors via an external button.

Multiple ActionTrigger items can be created. Each ActionTrigger assigns one or more actions to a specific event (see trigger_sources in /api/sensor/capabilities). Multiple ActionTriggers may refer to the same event (see order of execution below for details).

The actions assigned to an ActionTrigger are evaluated separately. Thus it is possible to specify the same action (even with the same parameters) multiple times. The list of actions for an ActionTrigger may be empty.

The actions within a single ActionTrigger are executed successively according to the order of the list items. The order of execution among multiple ActionTrigger items is undefined.

Trigger Events describing a state change (e.g. trigger_0_edge_rising) are emitted only once at the moment of the state change. Thus attached actions are executed only once for every state change.

Trigger Events describing a state (e.g. trigger_0_level_low) are emitted continuously as long as the state is active. The actions of an ActionTrigger attached to such a Trigger Event are executed periodically. After every execution of such an ActionTrigger further executions are skipped for a period of one second or until the next state change (whichever comes first). The only exception for this periodically executed actions is the enable_switching_output action. If this action is attached to a state, then it is re-evaluated whenever the hold time of the currently detected macher expires (i.e. for matchers with hold time zero: in every sample period).

The following flowchart visualizes the processing of trigger inputs. Processing of action triggers

See actions for a list of supported actions.

Request

Query Parameters

event UUID (string), pattern: `^[a-f0-9-]+$`, optional, read-only	Filter ActionTriggers by the given event name (e.g. trigger_0_edge_rising).

Response

Body

application/json

Properties (object)

data

object, required

data

action-triggers

Array of ActionTrigger, required

ActionTrigger[]

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

event

TriggerEventName (string), required

Any of the event names provided by /api/sensor/capabilities (attribute trigger_sources) is allowed.

actions

Array of Action, required

List of actions to be executed after the given event.

Action[]

name string, required	Unique name of the action
arguments object, required	arguments

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Remove multiple or all ActionTriggers ¶
DELETE /sensor/action-triggers Permission Scope sensor

Remove a selection of ActionTriggers either based on a given filter argument (if supported for this collection) or remove all ActionTriggers from the collection.

Request

Query Parameters

event UUID (string), pattern: `^[a-f0-9-]+$`, optional, read-only	Delete all ActionTriggers assigned to a given event name (e.g. trigger_0_edge_rising).

Response

The empty response indicates success

Create ActionTriggers ¶
POST /sensor/action-triggers Permission Scope sensor

Create a new ActionTrigger

All supported data attributes in the body of the request are optional.

Request

Body

application/json

Properties (ActionTrigger)

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

event

TriggerEventName (string), required

Any of the event names provided by /api/sensor/capabilities (attribute trigger_sources) is allowed.

actions

Array of Action, required

List of actions to be executed after the given event.

Action[]

name string, required	Unique name of the action
arguments object, required	arguments

Example

{
  "uuid": "3f26aff4-8650-42a0-b319-51776c443fbc",
  "event": "trigger_0_edge_falling",
  "actions": [
    {
      "name": "enable_switching_output",
      "arguments": {}
    }
  ]
}

Response

Body

application/json

Properties (object)

data

ActionTrigger, required

An Action Trigger assigns a given set of actions with an event.

At the end of each sample period, all events are evaluated. All corresponding actions are executed afterwards.

ActionTrigger

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

event

TriggerEventName (string), required

Any of the event names provided by /api/sensor/capabilities (attribute trigger_sources) is allowed.

actions

Array of Action, required

List of actions to be executed after the given event.

Action[]

name string, required	Unique name of the action
arguments object, required	arguments

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.validation.collection_size_exceeded

Input validation failed

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.validation.collection_size_exceeded

Delete ActionTrigger ¶
DELETE /sensor/action-triggers/{itemId} Permission Scope sensor

Deletes a single ActionTrigger

Request

Path Variables

itemId string, required

Response

The empty response indicates success

May return the following error codes

LPLC.not_found.collection.item

Modify ActionTrigger ¶
PUT /sensor/action-triggers/{itemId} Permission Scope sensor

Modifies a single ActionTrigger

Request

Path Variables

itemId string, required

Body

application/json

Properties (ActionTrigger)

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

event

TriggerEventName (string), required

Any of the event names provided by /api/sensor/capabilities (attribute trigger_sources) is allowed.

actions

Array of Action, required

List of actions to be executed after the given event.

Action[]

name string, required	Unique name of the action
arguments object, required	arguments

Example

{
  "uuid": "3f26aff4-8650-42a0-b319-51776c443fbc",
  "event": "trigger_0_edge_falling",
  "actions": [
    {
      "name": "enable_switching_output",
      "arguments": {}
    }
  ]
}

Response

Body

application/json

Properties (object)

data

ActionTrigger, required

An Action Trigger assigns a given set of actions with an event.

At the end of each sample period, all events are evaluated. All corresponding actions are executed afterwards.

ActionTrigger

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

event

TriggerEventName (string), required

Any of the event names provided by /api/sensor/capabilities (attribute trigger_sources) is allowed.

actions

Array of Action, required

List of actions to be executed after the given event.

Action[]

name string, required	Unique name of the action
arguments object, required	arguments

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.not_found.collection.item

Input validation failed

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.not_found.collection.item

Item not found

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.not_found.collection.item

Get ActionTrigger ¶
GET /sensor/action-triggers/{itemId} Permission Scope sensor

Returns a single ActionTrigger

Request

Path Variables

itemId string, required

Response

Body

application/json

Properties (object)

data

ActionTrigger, required

An Action Trigger assigns a given set of actions with an event.

At the end of each sample period, all events are evaluated. All corresponding actions are executed afterwards.

ActionTrigger

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

event

TriggerEventName (string), required

Any of the event names provided by /api/sensor/capabilities (attribute trigger_sources) is allowed.

actions

Array of Action, required

List of actions to be executed after the given event.

Action[]

name string, required	Unique name of the action
arguments object, required	arguments

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.not_found.collection.item

Get sensoric Capabilities ¶
GET /sensor/capabilities Permission Scope sensor

Response

Body

application/json

Properties (object)

data

SensorCapabilities, required

Provide access to the sensoric details supported by this device (e.g. colorspaces, input and output lines, ...).

SensorCapabilities

maximum_sample_rate

integer, required

the maximum sample rate the sensor supports

tolerances

Array of ColorTolerance (union), required

List of tolerance specifications supported by the sensor

InfiniteColorTolerance[]

limits object, required	limits
shape ToleranceShapeName (string), required	Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via `/api/sensor/capabilities`.

SphereColorTolerance[]

limits

object, required

limits

radius number, required

shape

ToleranceShapeName (string), required

Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via /api/sensor/capabilities.

CylinderColorTolerance[]

limits

object, required

limits

radius number, required
half_height number, required

shape

ToleranceShapeName (string), required

Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via /api/sensor/capabilities.

BoxColorTolerance[]

limits

object, required

limits

half_edges Array of number, minimum items: 3, maximum items: 3, required

shape

ToleranceShapeName (string), required

Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via /api/sensor/capabilities.

output_drivers

Array of SwitchingOutputDriver (string), required

List of supported electrical output drivers

trigger_sources

Array of TriggerSource, required

Contains the list of available trigger source with their corresponding trigger events. Trigger events can be automated to execute certain actions.

TriggerSource[]

name

string, required

Name of the trigger input

events

Array of TriggerEvent, required

TriggerEvent[]

name TriggerEventName (string), required

output_pin_count

integer, required

Number of available switching output lines

actions

Array of Action, required, Deprecated

Deprecated: use /api/actions instead

Action[]

name string, required	Unique name of the action
arguments object, required	arguments

colorspaces

Array of Colorspace, required

List of supported colorspaces.

Colorspace[]

name

string, required

space_id

ColorspaceID, required

Unique name of a colorspace

axes

Array of ColorspaceAxis, minimum items: 3, maximum items: 3, required

ColorspaceAxis[]

id string, required	Unique name
label string, required	Human-readable name
minimum number, required	lowest expected value of a color along this axis under usual circumstances
maximum number, required	highest expected value of a color along this axis under usual circumstances

colorspace_tolerance_maps

Array of ColorspaceToleranceMap, required

The evaluation of tolerances against positions of detectables depends on the currently configured colorspace. For example the tolerance attribute "half_height" refers to the brightness-related axis of a colorspace (e.g. "L*" for the "Lab*" colorspace) and is used for the height of the cylindrical tolerance shape and the first edge of the box tolerance shape.

The hue-related attributes (e.g. "a" and "b" for the "Lab*" colorspace) are used for the "radius" of a cylinder tolerance shape and the second and third edges of the box tolerance shape.

The colorspace_tolerance_maps define these relationships between colorspaces and tolerances.

ColorspaceToleranceMap[]

colorspace_id

ColorspaceID (string), required

Unique name of a colorspace

tolerance_shape

ToleranceShapeName (string), required

Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via /api/sensor/capabilities.

limits_axes_map

object, required

limits_axes_map

half_height Array of string, optional
half_edges Array of string, optional
radius Array of string, optional

settings_categories

Array of string, required

List of categories that can be selected during import to control which settings should be applied. See the documentation for the POST request to `/api/seetings.

maximum_detectables_count

integer, required

Maximum number of color positions (Detectable) to be stored in a detection profile.

maximum_matchers_count

integer, required

Maximum number of detection results (Matcher) be stored in a detection profile.

features

Array of string, required

List of specific sensor feature flags describing the supported operations of this sensor.

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Retrieve Colorspaces ¶
GET /sensor/colorspaces Permission Scope sensor

Retrieves a list of available Colorspaces

Response

Body

application/json

Properties (object)

data

object, required

data

colorspaces

Array of Colorspace, required

Colorspace[]

name

string, required

space_id

ColorspaceID, required

Unique name of a colorspace

axes

Array of ColorspaceAxis, minimum items: 3, maximum items: 3, required

ColorspaceAxis[]

id string, required	Unique name
label string, required	Human-readable name
minimum number, required	lowest expected value of a color along this axis under usual circumstances
maximum number, required	highest expected value of a color along this axis under usual circumstances

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Get Colorspace ¶
GET /sensor/colorspaces/{space_id} Permission Scope sensor

Returns a single Colorspace

Request

Path Variables

space_id string, required

Response

Body

application/json

Properties (object)

data

Colorspace, required

A colorspace describes the numeric conversion of colors under certain circumstances. Different standardized colorspaces are suitable for different detection tasks.

Colorspace

name

string, required

space_id

ColorspaceID, required

Unique name of a colorspace

axes

Array of ColorspaceAxis, minimum items: 3, maximum items: 3, required

ColorspaceAxis[]

id string, required	Unique name
label string, required	Human-readable name
minimum number, required	lowest expected value of a color along this axis under usual circumstances
maximum number, required	highest expected value of a color along this axis under usual circumstances

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.not_found.collection.item

Settings

Management of all device settings

Export Settings ¶
GET /settings

Export the complete configuration of the device.

Response

Textual representation of the complete device configuration. This configuration export can be uploaded to the same or another sensor without modifications.

The configuration data is encoded as Base64. The Base64 encoding is supposed to signal, that the configuration data dump is not meant to be manipulated or inspected automatically. You may not rely on a specific internal structure as it may change over time without further notice.

Body

text/plain

Upload Settings ¶
POST /settings

Replace the device configuration with the one being uploaded.

If you only want to partially import the settings you can do so by specifying one or more import categories. If you don’t specify at least one import category the default is to import all of them.

Import Category Key	Will import
import_category_access	Users, roles and permissions
import_category_firmware	Firmware settings (like the branch, but not the firmware itself)
import_category_keypad	Keypad settings
import_category_network	Network configuration
import_category_outputs	Output driver
import_category_sensor	Matchers (color groups), detectables (colors), colorspace, sample configuration
import_category_system	System settings (like timezone and hostname)

A machine-readable list of import categories is returned by the /api/sensor/capabilities endpoint under the settings_categories key.

Settings exported from older firmwares will automatically be migrated to the new format required by the sensor. In case a migration fails the response will contain the LPLC.migration.execution_failed error code. Settings from more recent firmwares than the one used on the sensor MAY fail on import, if the settings format is no longer compatible. In that case the response will contain the LPLC.migration.future_version error code.

Request

Body

multipart/form-data

Properties (object)

settings_file file, required	The settings file containing a Base64 encoded configuration dump. See GET request for `/api/settings`.
/^import_category_.+/ any, optional	Import only a specific subset of the configuration.

Response

The empty response indicates success

May return the following error codes

LPLC.format.encoding.utf8
LPLC.format.malformed.base64
LPLC.validation.missing_input
LPLC.format.malformed.json
LPLC.format.malformed.json.not_dict
LPLC.migration.future_version
LPLC.migration.execution_failed

Input validation failed

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.format.encoding.utf8
LPLC.format.malformed.base64
LPLC.validation.missing_input
LPLC.format.malformed.json
LPLC.format.malformed.json.not_dict
LPLC.migration.future_version
LPLC.migration.execution_failed

Import Settings ¶
PUT /settings

Replace the complete device configuration with the uploaded configuration dump.

The content to be uploaded can be retrieved via a GET request on /api/settings. This Base64 encoded configuration dump is expected as the request body.

If you only want to partially import the settings you can do so by specifying one or more import categories. If you don’t specify at least one import category the default is to import all of them.

Import Category Key	Will import
import_category_access	Users, roles and permissions
import_category_firmware	Firmware settings (like the branch, but not the firmware itself)
import_category_keypad	Keypad settings
import_category_network	Network configuration
import_category_outputs	Output driver
import_category_sensor	Matchers (color groups), detectables (colors), colorspace, sample configuration
import_category_system	System settings (like timezone and hostname)

A machine-readable list of import categories is returned by the /api/sensor/capabilities endpoint under the settings_categories key.

Request

Body

text/plain

Properties (object)

/^import_category_.+/ any, optional	Import only a specific subset of the configuration.

Response

The empty response indicates success

May return the following error codes

LPLC.format.encoding.utf8
LPLC.format.malformed.base64
LPLC.format.malformed.json
LPLC.format.malformed.json.not_dict
LPLC.migration.future_version
LPLC.migration.execution_failed

Input validation failed

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.format.encoding.utf8
LPLC.format.malformed.base64
LPLC.format.malformed.json
LPLC.format.malformed.json.not_dict
LPLC.migration.future_version
LPLC.migration.execution_failed

Reset Settings ¶
DELETE /settings

Reset the device configuration to the factory defaults.

Response

The empty response indicates success

System

Manage the device's system settings

Request System Settings ¶
GET /system

Response

Body

application/json

Properties (object)

data

SystemSettings, required

SystemSettings

hostname Hostname, pattern: `^(?:[a-zA-Z0-9](?:[a-zA-Z0-9\-][a-zA-Z0-9])?\.)[a-zA-Z0-9](?:[a-zA-Z0-9\-]*[a-zA-Z0-9])?$`, optional	Human-readable name identifying the device in the network
uptime any of number or null, optional, read-only	The current system uptime in seconds. Though highly unlikely can be nil in case the system reported an invalid value.

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Modify System Settings ¶
PUT /system

Request

Body

application/json

Properties (SystemSettings)

hostname Hostname, pattern: `^(?:[a-zA-Z0-9](?:[a-zA-Z0-9\-][a-zA-Z0-9])?\.)[a-zA-Z0-9](?:[a-zA-Z0-9\-]*[a-zA-Z0-9])?$`, optional	Human-readable name identifying the device in the network
uptime any of number or null, optional, read-only	The current system uptime in seconds. Though highly unlikely can be nil in case the system reported an invalid value.

Example

{
  "hostname": "blickwerk-7454232361"
}

Response

Body

application/json

Properties (object)

data

SystemSettings, required

SystemSettings

hostname Hostname, pattern: `^(?:[a-zA-Z0-9](?:[a-zA-Z0-9\-][a-zA-Z0-9])?\.)[a-zA-Z0-9](?:[a-zA-Z0-9\-]*[a-zA-Z0-9])?$`, optional	Human-readable name identifying the device in the network
uptime any of number or null, optional, read-only	The current system uptime in seconds. Though highly unlikely can be nil in case the system reported an invalid value.

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.system.action_failed

Input validation failed

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.system.action_failed

Internal server error

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.system.action_failed

Reset to Factory Firmware and Settings ¶
POST /system/factory-reset Permission Scope system

Reset the sensor's firmware to its factory default and initiate a reboot. After completion the sensor will use its original ("recovery") firmware and all settings are reset to their defaults. The recovery firmware can be upgraded via "/firmware/upgrade-from-current".

In case you only want to reset the settings it is sufficient to send a DELETE request to the /api/settings endpoint.

Response

The empty response indicates success

May return the following error codes

LPLC.system.action_failed

Internal server error

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.system.action_failed

Initiate Reboot ¶
POST /system/reboot Permission Scope system

Reboots the device.

The software-triggered reboot is the more polite method to shutdown the sensor compared to unplugging the power supply. However the latter is safe as well.

Response

The empty response indicates success

May return the following error codes

LPLC.system.action_failed

Internal server error

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.system.action_failed

Get time settings ¶
GET /system/time Permission Scope system

Response

Body

application/json

Properties (object)

data

SystemTimeSettings, required

SystemTimeSettings

now Timestamp (string), optional	current time from the perspective of the sensor
timezone string, optional	currently configured timezone
ntp_servers Array of string, optional	one or more network time servers
default_ntp_servers Array of string, optional, read-only	preconfigured network time servers

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Change time settings ¶
PUT /system/time Permission Scope system

Request

Body

application/json

Properties (SystemTimeSettings)

now Timestamp (string), optional	current time from the perspective of the sensor
timezone string, optional	currently configured timezone
ntp_servers Array of string, optional	one or more network time servers
default_ntp_servers Array of string, optional, read-only	preconfigured network time servers

Example

{
  "now": "2018-01-24T15:45:15.694004+01:00",
  "timezone": "Europe/Berlin",
  "ntp_servers": [
    "pool.ntp.org"
  ],
  "default_ntp_servers": [
    "pool.ntp.org"
  ]
}

Response

Body

application/json

Properties (object)

data

SystemTimeSettings, required

SystemTimeSettings

now Timestamp (string), optional	current time from the perspective of the sensor
timezone string, optional	currently configured timezone
ntp_servers Array of string, optional	one or more network time servers
default_ntp_servers Array of string, optional, read-only	preconfigured network time servers

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.system.action_failed
LPLC.validation.readonly
LPLC.validation.readonly

Input validation failed

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.system.action_failed
LPLC.validation.readonly
LPLC.validation.readonly

Internal server error

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.system.action_failed
LPLC.validation.readonly
LPLC.validation.readonly

Retrieve supported Timezones. ¶
GET /system/time/zones Permission Scope system

The device contains knowledge about an exhaustive list of officially standardized timezones. The sensor should be configured either with a local timezone or with UTC.

Response

Body

application/json

Properties (object)

data

object, required

data

timezone_names Array of string, required	List of timezones supported by the device

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Network

The services of the sensor device are accessible via network connections. The network interfaces of the device can be configured for all standard compliant network setups.

Reset Network Settings ¶
DELETE /network

Reset networking settings to factory defaults

Response

The empty response indicates success

Retrieve status and configuration of all network interfaces ¶
GET /network/interfaces Permission Scope network

Returns a list of network interfaces.

Each network interface has a MAC-Address (hardware_address), a unique interface name (iface) and indicates the current physical connection status (has_link).

Both IPv4 (ipv4) and IPv6 (ipv6) are supported, both with their current configuration (address_configurations) and actual interface addresses (current_addresses).

Interface addresses are in CIDR notation starting with the interface address, followed by slash and ending with a decimal number representing the subnet mask (IPv4) or prefix length (IPv6).

The collection itself is read-only as no new interfaces can be added. You can change the individual interface configuration with PUT requests to a specific interface resource.

Response

Body

application/json

Properties (object)

data

Array of NetworkInterfaceAddressConfigurationState, required

NetworkInterfaceAddressConfigurationState[]

ipv4

NetworkInterfaceAddressFamilyStateIPv4, optional

IPv4 Network address configuration

ipv4

address_configurations

Array of any of NetworkAddressConfigurationIPv4Static or NetworkAddressConfigurationIPv4DHCP, optional

NetworkAddressConfigurationIPv4Static[]

method string, one of [`static`, `dhcp`], required	Configuration method used for the address.
address NetworkInterfaceAddressIPv4 (string), required	IPv4 network address in CIDR notation
gateway NetworkAddressIPv4 (string), optional	default gateway for outgoing traffic

NetworkAddressConfigurationIPv4DHCP[]

method string, one of [`static`, `dhcp`], required	Configuration method used for the address.

ipv6

NetworkInterfaceAddressFamilyStateIPv6, optional

IPv6 Network address configuration

ipv6

address_configurations

Array of any of NetworkAddressConfigurationIPv6Static, NetworkAddressConfigurationIPv6DHCP or NetworkAddressConfigurationIPv6Auto, optional

NetworkAddressConfigurationIPv6Static[]

method string, one of [`static`, `dhcp`, `auto`], required	Configuration method used for the address.
address NetworkInterfaceAddressIPv6 (string), required	IPv6 network address in CIDR notation
gateway NetworkAddressIPv6 (string), optional	default gateway for outgoing traffic

NetworkAddressConfigurationIPv6DHCP[]

method string, one of [`static`, `dhcp`, `auto`], required	Configuration method used for the address.

NetworkAddressConfigurationIPv6Auto[]

method string, one of [`static`, `dhcp`, `auto`], required	Configuration method used for the address.

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Retrieve status and configuration of a single network interface ¶
GET /network/interfaces/{name} Permission Scope network

Returns information, current status, address configuration, and current addresses for a single interface.

Request

Path Variables

name string, required

Response

Body

application/json

Properties (object)

data

NetworkInterfaceAddressConfigurationState, required

Configurable network address configuration of a network interface

NetworkInterfaceAddressConfigurationState

ipv4

NetworkInterfaceAddressFamilyStateIPv4, optional

IPv4 Network address configuration

ipv4

address_configurations

Array of any of NetworkAddressConfigurationIPv4Static or NetworkAddressConfigurationIPv4DHCP, optional

NetworkAddressConfigurationIPv4Static[]

method string, one of [`static`, `dhcp`], required	Configuration method used for the address.
address NetworkInterfaceAddressIPv4 (string), required	IPv4 network address in CIDR notation
gateway NetworkAddressIPv4 (string), optional	default gateway for outgoing traffic

NetworkAddressConfigurationIPv4DHCP[]

method string, one of [`static`, `dhcp`], required	Configuration method used for the address.

ipv6

NetworkInterfaceAddressFamilyStateIPv6, optional

IPv6 Network address configuration

ipv6

address_configurations

Array of any of NetworkAddressConfigurationIPv6Static, NetworkAddressConfigurationIPv6DHCP or NetworkAddressConfigurationIPv6Auto, optional

NetworkAddressConfigurationIPv6Static[]

method string, one of [`static`, `dhcp`, `auto`], required	Configuration method used for the address.
address NetworkInterfaceAddressIPv6 (string), required	IPv6 network address in CIDR notation
gateway NetworkAddressIPv6 (string), optional	default gateway for outgoing traffic

NetworkAddressConfigurationIPv6DHCP[]

method string, one of [`static`, `dhcp`, `auto`], required	Configuration method used for the address.

NetworkAddressConfigurationIPv6Auto[]

method string, one of [`static`, `dhcp`, `auto`], required	Configuration method used for the address.

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.not_found.collection.item

Modify IPv4 and/or IPv6 address configuration ¶
PUT /network/interfaces/{name} Permission Scope network

Interfaces are readonly except for their IPv6 and IPv4 address configurations.

You can set new address configurations by providing the address_configurations key in the respective IP address family object(ipv4 or ipv6). address_configurations will replace any existing configuration with the new configuration. If you only want to add a new configuration be sure to submit any existing ones as well.

The address_configurations list only affects their respective address family. If you only want to alter the IPv4 address configuration it is sufficient to set the ipv4.address_configurations key. Any other address family will remain unaffected as long as you do not alter their own address_configuration list as well.

The response to a network configuration change request is returned before the new configuration is applied. This ensures that the caller receives an acknowledgment from the API before the network connection may get lost due to the changed configuration. The reconfiguration of the new network setup happens in the background shortly after the response is emitted. Thus the API may close existing connection and will not respond to further requests for a few seconds. Please note that only one configuration change may be requested at a time. Thus the API will delay the response to a second request until all internal processes for the first request are finished. Such a response to a quick subsequent request may be delayed by up to 20 seconds. If too many parallel requests are competing for network setup changes, the HTTP status response 423 (Locked) will be returned after a timeout of 20 seconds.

Please Note: Even though the API supports multiple address configurations for each address family only the first will be applied at the moment. This is a pending feature. Therefore you should only provide one address configuration item per address family.

Request

Path Variables

name string, required

Body

application/json

Properties (NetworkInterfaceInformation)

iface

NetworkInterfaceName (string), pattern: ^[a-z0-9-]+$, required, read-only

unique name describing a network interface

hardware_address

MacAddress (string), pattern: ^([a-f0-9]{2}:){5}[a-f0-9]{2}$, required, read-only

unique hardware address of a network interface

has_link

boolean, required, read-only

current physical connection status (whether a cable is plugged in or not)

ipv4

NetworkInterfaceAddressFamilyStateIPv4, optional

IPv4 Network address configuration

ipv4

address_configurations

Array of any of NetworkAddressConfigurationIPv4Static or NetworkAddressConfigurationIPv4DHCP, optional

NetworkAddressConfigurationIPv4Static[]

method string, one of [`static`, `dhcp`], required	Configuration method used for the address.
address NetworkInterfaceAddressIPv4 (string), required	IPv4 network address in CIDR notation
gateway NetworkAddressIPv4 (string), optional	default gateway for outgoing traffic

NetworkAddressConfigurationIPv4DHCP[]

method string, one of [`static`, `dhcp`], required	Configuration method used for the address.

ipv6

NetworkInterfaceAddressFamilyStateIPv6, optional

IPv6 Network address configuration

ipv6

address_configurations

Array of any of NetworkAddressConfigurationIPv6Static, NetworkAddressConfigurationIPv6DHCP or NetworkAddressConfigurationIPv6Auto, optional

NetworkAddressConfigurationIPv6Static[]

method string, one of [`static`, `dhcp`, `auto`], required	Configuration method used for the address.
address NetworkInterfaceAddressIPv6 (string), required	IPv6 network address in CIDR notation
gateway NetworkAddressIPv6 (string), optional	default gateway for outgoing traffic

NetworkAddressConfigurationIPv6DHCP[]

method string, one of [`static`, `dhcp`, `auto`], required	Configuration method used for the address.

NetworkAddressConfigurationIPv6Auto[]

method string, one of [`static`, `dhcp`, `auto`], required	Configuration method used for the address.

Remove all IPv6 address configurations

{
  "ipv6": {
    "address_configurations": []
  }
}

Replace existing IPv4 configuration with DHCP

{
  "ipv4": {
    "address_configurations": [
      {
        "method": "dhcp"
      }
    ]
  }
}

Set static and dynamic IPv4 configuration

{
  "ipv4": {
    "address_configurations": [
      {
        "method": "dhcp"
      },
      {
        "method": "static",
        "address": "192.168.0.100/24"
      }
    ]
  }
}

Response

Body

application/json

Properties (object)

data

NetworkInterfaceAddressConfigurationState, required

Configurable network address configuration of a network interface

NetworkInterfaceAddressConfigurationState

ipv4

NetworkInterfaceAddressFamilyStateIPv4, optional

IPv4 Network address configuration

ipv4

address_configurations

Array of any of NetworkAddressConfigurationIPv4Static or NetworkAddressConfigurationIPv4DHCP, optional

NetworkAddressConfigurationIPv4Static[]

method string, one of [`static`, `dhcp`], required	Configuration method used for the address.
address NetworkInterfaceAddressIPv4 (string), required	IPv4 network address in CIDR notation
gateway NetworkAddressIPv4 (string), optional	default gateway for outgoing traffic

NetworkAddressConfigurationIPv4DHCP[]

method string, one of [`static`, `dhcp`], required	Configuration method used for the address.

ipv6

NetworkInterfaceAddressFamilyStateIPv6, optional

IPv6 Network address configuration

ipv6

address_configurations

Array of any of NetworkAddressConfigurationIPv6Static, NetworkAddressConfigurationIPv6DHCP or NetworkAddressConfigurationIPv6Auto, optional

NetworkAddressConfigurationIPv6Static[]

method string, one of [`static`, `dhcp`, `auto`], required	Configuration method used for the address.
address NetworkInterfaceAddressIPv6 (string), required	IPv6 network address in CIDR notation
gateway NetworkAddressIPv6 (string), optional	default gateway for outgoing traffic

NetworkAddressConfigurationIPv6DHCP[]

method string, one of [`static`, `dhcp`, `auto`], required	Configuration method used for the address.

NetworkAddressConfigurationIPv6Auto[]

method string, one of [`static`, `dhcp`, `auto`], required	Configuration method used for the address.

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.validation
LPLC.not_found.collection.item

Input validation failed

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.validation
LPLC.not_found.collection.item

Item not found

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.validation
LPLC.not_found.collection.item

The resource is currently in use. Try again later.

May return the following error codes

LPLC.validation
LPLC.not_found.collection.item

Peripherals

Get Keypad Information ¶
GET /peripherals/keypad Permission Scope peripherals

Retrieve basic information about the keypad.

Response

Body

application/json

Properties (object)

data

KeypadInformation, required

Describe the current state of the keypad as well as access to visualization data.

KeypadInformation

locked boolean, required	Boolean flag indicating the state of the key lock (true -> locked, false -> unlocked). All keypad inputs are ignored while the lock is active.
clear_matcher_before_teach boolean, required	The boolean flag controls whether multiple detectables can be stored for a matcher via keypad-based teach operations. A value of true implies, that a teach operation always removes all existing detectables from the currently selected matcher before adding the new detectable. With a value of false previously existing detectables are not deleted before a new one is added.
visualization_url any of string or null, optional, read-only	The visualization resource location can be used for providing a virtual keypad interface. Its URL may start with a scheme (e.g. http or https) for a full URL including hostname or it may start with a slash, indicating a path provided by the device itself. This attribute cannot be modified.

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Modify Keypad ¶
PUT /peripherals/keypad Permission Scope peripherals

Modify basic states of the keypad.

Request

Body

application/json

Properties (KeypadInformation)

locked boolean, required	Boolean flag indicating the state of the key lock (true -> locked, false -> unlocked). All keypad inputs are ignored while the lock is active.
clear_matcher_before_teach boolean, required	The boolean flag controls whether multiple detectables can be stored for a matcher via keypad-based teach operations. A value of true implies, that a teach operation always removes all existing detectables from the currently selected matcher before adding the new detectable. With a value of false previously existing detectables are not deleted before a new one is added.
visualization_url any of string or null, optional, read-only	The visualization resource location can be used for providing a virtual keypad interface. Its URL may start with a scheme (e.g. http or https) for a full URL including hostname or it may start with a slash, indicating a path provided by the device itself. This attribute cannot be modified.

Example

{
  "locked": true,
  "clear_matcher_before_teach": false,
  "visualization_url": "/media/keypad-image.svg"
}

Response

Body

application/json

Properties (object)

data

KeypadInformation, required

Describe the current state of the keypad as well as access to visualization data.

KeypadInformation

locked boolean, required	Boolean flag indicating the state of the key lock (true -> locked, false -> unlocked). All keypad inputs are ignored while the lock is active.
clear_matcher_before_teach boolean, required	The boolean flag controls whether multiple detectables can be stored for a matcher via keypad-based teach operations. A value of true implies, that a teach operation always removes all existing detectables from the currently selected matcher before adding the new detectable. With a value of false previously existing detectables are not deleted before a new one is added.
visualization_url any of string or null, optional, read-only	The visualization resource location can be used for providing a virtual keypad interface. Its URL may start with a scheme (e.g. http or https) for a full URL including hostname or it may start with a slash, indicating a path provided by the device itself. This attribute cannot be modified.

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.validation

Input validation failed

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.validation

Retrieve user interactions on the keypad ¶
GET /peripherals/keypad/events Permission Scope peripherals

Return a list of keypad events.

This collection is implemented as a ring-buffer meaning that older Events will be removed once new events are added.

Response

Body

application/json

Properties (object)

events

Array of KeypadEvent, required

KeypadEvent[]

source string, required	The usual source of events is inputs.
name KeypadEventInput (string), required	Name of a keypad input (button) that may trigger events.
event KeypadEventName (string), required	Input peripherals can trigger different events.
timestamp integer, minimum: 0, required	The timestamp is given in milliseconds and should be monotonic increasing.

Retrieve a list of available input elements on the keypad ¶
GET /peripherals/keypad/inputs Permission Scope peripherals

Returns a list of keypad input elements.

Every keypad input element represents a physical button on the keypad.

Response

Body

application/json

Properties (object)

data

object, required

data

inputs

Array of KeypadInputButton, required

KeypadInputButton[]

name

KeypadEventInput (string), required

Name of a keypad input (button) that may trigger events.

capabilities

Array of object, required

object[]

name KeypadEventName (string), required	Input peripherals can trigger different events.
url string, required	The event can be triggered externally by submitting a POST request against this resource.

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Simulate a user interaction on the keypad ¶
POST /peripherals/keypad/inputs/{name}/{event} Permission Scope peripherals

Simulates a button-press by externally triggering the given event for the input.

See the collection of keypad inputs for a list or URLs available for triggering events.

Request

Path Variables

name string, required
event string, required

Response

The empty response indicates success

May return the following error codes

LPLC.resource.unspecified
LPLC.resource.invalid
LPLC.illegal_request

Item not found

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.resource.unspecified
LPLC.resource.invalid
LPLC.illegal_request

Get Output Configuration ¶
GET /peripherals/outputs Permission Scope peripherals

Response

Body

application/json

Properties (object)

data

SwitchingOutputs, required

Eletrical output lines can drive external actors in different electrical modes.

SwitchingOutputs

output_driver SwitchingOutputDriver (string), required	The Output Driver defines the electrical behaviour of the switching outputs. The supported output drivers can be retrieved via `/api/sensor/capabilities`.
count integer, required	Number of available output lines

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Modify Output Configuration ¶
PUT /peripherals/outputs Permission Scope peripherals

Request

Body

application/json

Properties (SwitchingOutputsWritable)

output_driver SwitchingOutputDriver (string), required	The Output Driver defines the electrical behaviour of the switching outputs. The supported output drivers can be retrieved via `/api/sensor/capabilities`.

Response

Body

application/json

Properties (object)

data

SwitchingOutputs, required

Eletrical output lines can drive external actors in different electrical modes.

SwitchingOutputs

output_driver SwitchingOutputDriver (string), required	The Output Driver defines the electrical behaviour of the switching outputs. The supported output drivers can be retrieved via `/api/sensor/capabilities`.
count integer, required	Number of available output lines

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.validation

Input validation failed

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.validation

Get current interface configuration ¶
GET /peripherals/rs232 Permission Scope peripherals

Response

Body

application/json

Properties (object)

data

InterfaceRS232, required

InterfaceRS232

protocol

any of SerialDisabledSettings, SerialModbusSettings or SerialElizaSettings, required

SerialDisabledSettings

type string, one of [`eliza`, `modbus`, `nil`] , default: `eliza`, required

SerialModbusSettings

type string, one of [`eliza`, `modbus`, `nil`] , default: `eliza`, required
slave_id any of number or null, required
frame_format string, one of [`rtu`, `ascii`] , default: `rtu`, required

SerialElizaSettings

type string, one of [`eliza`, `modbus`, `nil`] , default: `eliza`, required

supported_protocols

Array of string, optional, read-only

baud_rate

number, one of [9600, 19200, 115200], required

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Modify interface configuration ¶
PUT /peripherals/rs232 Permission Scope peripherals

Request

Body

application/json

Properties (InterfaceRS232)

protocol

any of SerialDisabledSettings, SerialModbusSettings or SerialElizaSettings, required

SerialDisabledSettings

type string, one of [`eliza`, `modbus`, `nil`] , default: `eliza`, required

SerialModbusSettings

type string, one of [`eliza`, `modbus`, `nil`] , default: `eliza`, required
slave_id any of number or null, required
frame_format string, one of [`rtu`, `ascii`] , default: `rtu`, required

SerialElizaSettings

type string, one of [`eliza`, `modbus`, `nil`] , default: `eliza`, required

supported_protocols

Array of string, optional, read-only

baud_rate

number, one of [9600, 19200, 115200], required

Response

Body

application/json

Properties (object)

data

InterfaceRS232, required

InterfaceRS232

protocol

any of SerialDisabledSettings, SerialModbusSettings or SerialElizaSettings, required

SerialDisabledSettings

type string, one of [`eliza`, `modbus`, `nil`] , default: `eliza`, required

SerialModbusSettings

type string, one of [`eliza`, `modbus`, `nil`] , default: `eliza`, required
slave_id any of number or null, required
frame_format string, one of [`rtu`, `ascii`] , default: `rtu`, required

SerialElizaSettings

type string, one of [`eliza`, `modbus`, `nil`] , default: `eliza`, required

supported_protocols

Array of string, optional, read-only

baud_rate

number, one of [9600, 19200, 115200], required

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.validation
LPLC.validation.readonly

Input validation failed

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.validation
LPLC.validation.readonly

Get trigger source event statistics ¶
GET /peripherals/trigger-sources Permission Scope peripherals

Response

Body

application/json

Properties (object)

data

TriggerSourcesStatus, required

The sensor has a number of input lines that can be used as trigger sources. The event counters are updated periodically (approximately every second).

TriggerSourcesStatus

trigger_sources

Array of object, required

object[]

name

string, required

event_counters

object, required

event_counters

edge_falling number, required
edge_rising number, required
level_low number, required
level_high number, required

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Get current interface configuration ¶
GET /peripherals/usb Permission Scope peripherals

Response

Body

application/json

Properties (object)

data

InterfaceUSB, required

InterfaceUSB

protocol

any of SerialDisabledSettings, SerialModbusSettings or SerialElizaSettings, required

SerialDisabledSettings

type string, one of [`eliza`, `modbus`, `nil`] , default: `eliza`, required

SerialModbusSettings

type string, one of [`eliza`, `modbus`, `nil`] , default: `eliza`, required
slave_id any of number or null, required
frame_format string, one of [`rtu`, `ascii`] , default: `rtu`, required

SerialElizaSettings

type string, one of [`eliza`, `modbus`, `nil`] , default: `eliza`, required

supported_protocols

Array of string, optional, read-only

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Modify interface configuration ¶
PUT /peripherals/usb Permission Scope peripherals

Request

Body

application/json

Properties (InterfaceUSB)

protocol

any of SerialDisabledSettings, SerialModbusSettings or SerialElizaSettings, required

SerialDisabledSettings

type string, one of [`eliza`, `modbus`, `nil`] , default: `eliza`, required

SerialModbusSettings

type string, one of [`eliza`, `modbus`, `nil`] , default: `eliza`, required
slave_id any of number or null, required
frame_format string, one of [`rtu`, `ascii`] , default: `rtu`, required

SerialElizaSettings

type string, one of [`eliza`, `modbus`, `nil`] , default: `eliza`, required

supported_protocols

Array of string, optional, read-only

Response

Body

application/json

Properties (object)

data

InterfaceUSB, required

InterfaceUSB

protocol

any of SerialDisabledSettings, SerialModbusSettings or SerialElizaSettings, required

SerialDisabledSettings

type string, one of [`eliza`, `modbus`, `nil`] , default: `eliza`, required

SerialModbusSettings

type string, one of [`eliza`, `modbus`, `nil`] , default: `eliza`, required
slave_id any of number or null, required
frame_format string, one of [`rtu`, `ascii`] , default: `rtu`, required

SerialElizaSettings

type string, one of [`eliza`, `modbus`, `nil`] , default: `eliza`, required

supported_protocols

Array of string, optional, read-only

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.validation
LPLC.validation.readonly

Input validation failed

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.validation
LPLC.validation.readonly

Actions

This endpoint provides details for all available actions. Additionally actions can be executed for one-time operations.

See action-triggers if you want to connect trigger input line events with specific actions for repeated operations.

Action descriptions

Every action accepts a a distinct set of optional or mandatory arguments. They are summarized in the argument field of each action in the collection. The detailed description of their meaning and the specification of each Action's behaviour is described below.

Action "enable_switching_output"

The behavior of the switching outputs changes significantly while this action is configured for at least one trigger event. See the introduction chapter about Switching outputs, triggers and hold time settings for a detailed specification of the different behaviors.

Arguments: none

Action "teach_single"

Sample a new detectable whenever the action is executed.

Arguments:

matcher_id (optional, default: null): the UUID of a matcher or null. In case of null the new detectable is assigned to a matcher based on matcher_output_pattern. In case of the ID belonging to an existing matcher, the new detectable is assigned to this matcher. In case of an ID that does not belong to an existing matcher, a matcher with this ID is created and assigned to the new detectable.
matcher_output_pattern (optional, default: null): output pattern of the target matcher. This field is only considered, if matcher_id is null. In case of matcher_output_pattern being null, a new matcher is created whenever the action is executed. Otherwise the matcher_output_pattern is expected to be a dictionary containing a states field. This states field is supposed to contain a list of boolean output states. If a matcher with this output pattern already exists, then the new detectable is added to this matcher. If no matcher with such an output pattern exists, then a new matcher for this output pattern is created before adding the new detectable to it.
remove_matcher_detectables_before (optional, default: true): the boolean value specifies whether detectables belonging to the selected matcher should be removed right before the new detectable is added.

Action "keylock"

Control the state of the keypad locking.

A typical approach could be to connect the rising edge of a trigger input to this action with the parameter locked being true and the falling edge of the same trigger input with false. Thus the locking state of the keypad would follow the level of the trigger input.

Arguments:

locked (required): the boolean value specifies the wanted target state of the keypad locking. The true value locks the keypad. The false value releases the lock.

Action "api_view_lock"

Control the state of the API locking for "view" requests. Any read requests are rejected, while the view lock is active.

Arguments:

locked (required): the boolean value specifies the wanted target state of the API view lock. The true value blocks any read requests. The false value releases the lock.

Action "api_edit_lock"

Control the state of the API locking for "edit" requests. Any write requests (PUT/POST/DELETE) are rejected, while the edit lock is active.

Arguments:

locked (required): the boolean value specifies the wanted target state of the API edit lock. The true value blocks any write requests. The false value releases the lock.

Action "run_autogain"

Start an autogain procedure.

Probably the action "remove_all_detectables" should be executed afterwards, since the color values may not be accurate anymore due to changed sampling settings.

Arguments: none

Action "remove_all_detectables"

Clear the detectables collection.

Arguments: none

Action "remove_all_matchers"

Clear the matchers collection. This also removes all detectables.

Arguments: none

Action "select_detection_profile"

Switch to the given detection profile.

Please note that the trigger actions belong to a specific profile. Thus you need to understand, that the trigger actions of the target detection profile are active after the switch. For the common use-case of toggling between two detection profiles via the rising and the falling edge of an input trigger line you need to define the following trigger actions in the respective detection profiles:

profile A: trigger action for switching to profile B in case of a rising edge
profile B: trigger action for switching to profile A in case of a falling edge

Arguments:

profile_id: the UUID of an existing detection profile.

Retrieve Actions ¶
GET /actions

Retrieves a list of available Actions

Response

Body

application/json

Properties (object)

data

object, required

data

actions

Array of Action, required

Action[]

name string, required	Unique name of the action
arguments object, required	arguments

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Get Action ¶
GET /actions/{itemId} Permission Scope sensor

Returns a single Action

Request

Path Variables

itemId string, required

Response

Body

application/json

Properties (object)

data

Action, required

The sensor allows the connection of events with actions. Actions can be related to the sensor operations or the information handled by the sensor (e.g. the list of stored detectables).

The Action consists of a unique name and a set of optional arguments.

The list of available Actions and their possible arguments can be retrieved via /api/actions.

Action

name string, required	Unique name of the action
arguments object, required	arguments

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.not_found.collection.item

Software-triggered Actions ¶
POST /actions/{itemId}/execute Permission Scope sensor

Execute the given action once. This provides access to all operations that can be connected to trigger input line events.

Additional parameters (if required by the action) can be provided in the body of the request. For example the keylock action could be executed by providing a dictionary containing the key locked with the wanted boolean target state. See the arguments field of each action in the collection above.

The content of the response depends on the specific action that was executed.

The example actions with their respective parameters and responses may not be supported by all sensors. The Actions collection contains the authoritative list of supported actions for each sensor.

Request

Path Variables

itemId string, required

Body

application/json

Properties (AnyAction (union))

ActionEnableSwitchingOutput

ActionEnableSwitchingOutput, optional

Apply the output_pattern of the currently detected matcher to the switching outputs of the sensor.

ActionEnableSwitchingOutput

name string, required	Unique name of the action
arguments object, required	arguments

ActionTeachDetectable

ActionTeachDetectable, optional

Add the currently sampled color as a Detectable to the selected matcher.

ActionTeachDetectable

arguments

object, required

arguments

matcher_id

UUID (string), pattern: ^[a-f0-9-]+$, optional, read-only

The new Detectable is assigned to the Matcher identified by this UUID. In case this matcher UUID (and "matcher_output_pattern") is undefined, a new matcher is created.

matcher_output_pattern:

object, optional

Pattern of the switching outputs to be used when selecting the target matcher for the new detectable. A suitable matcher is created, if no matcher with the specified pattern is found. This field is ignored, if "matcher_id" is not null. If no pattern is defined (an no "matcher_id"), then a new matcher is created whenever the corresponding action is executed.

matcher_output_pattern:

states Array of any of boolean or null, required	List of True/False values describing the wanted states of the Switching Outputs

remove_matcher_detectables_before

boolean , default: true, optional

Remove all Detectables belonging to the configured Matcher before attaching the new Detectable.

name

string, required

Unique name of the action

ActionKeyLock

ActionKeyLock, optional

Change the locked state of the keypad. This allows or disallows local access to the sensor via the keypad.

ActionKeyLock

arguments

object, required

arguments

locked boolean, required	Target state of the keypad locking.

name

string, required

Unique name of the action

ActionAPIViewLock

ActionAPIViewLock, optional

Change the locked state of API for write requests. This allows or disallows reading the sensor state via the API.

ActionAPIViewLock

arguments

object, required

arguments

locked boolean, required	Target state of the API view lock.

name

string, required

Unique name of the action

ActionAPIEditLock

ActionAPIEditLock, optional

Change the locked state of API for write requests. This allows or disallows changing sensor settings via the API.

ActionAPIEditLock

arguments

object, required

arguments

locked boolean, required	Target state of the API edit lock.

name

string, required

Unique name of the action

ActionRunAutogain

ActionRunAutogain, optional

Start an automatic adjustment of the optiocal sensor setup. See /api/sensor/detection-profiles/current/autogain for details.

ActionRunAutogain

name string, required	Unique name of the action
arguments object, required	arguments

ActionRemoveAllDetectables

ActionRemoveAllDetectables, optional

Remove all stored Detectables belonging to any Matcher.

ActionRemoveAllDetectables

name string, required	Unique name of the action
arguments object, required	arguments

ActionRemoveAllMatchers

ActionRemoveAllMatchers, optional

Remove all stored Matchers (including the related detectables).

ActionRemoveAllMatchers

name string, required	Unique name of the action
arguments object, required	arguments

ActionSelectDetectionProfile

ActionSelectDetectionProfile, optional

Switch to a detection profile.

ActionSelectDetectionProfile

name string, required	Unique name of the action
arguments object, required	arguments

Response

Body

application/json

Properties (object)

data

any of ActionResultEnableSwitchingOutput, ActionResultTeachDetectable, ActionResultKeyLock, ActionResultRunAutogain, ActionResultRemoveAllDetectables (string) or ActionResultRemoveAllMatchers (string), required

ActionResultEnableSwitchingOutput

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

timestamp

TimestampBackendUptime, required

The timestamp (given in microseconds) is based on the uptime of the internal analog sensor backend. It may get reset to zero under specific conditions.

corrected_color

CorrectedColor, required

Representation of a color in the colorspace XYZ.

corrected_color

values Array of number, minimum items: 3, maximum items: 3, required	Location in a colorspace

transformed_color

TransformedColor, required

A color represented by a coordinate in the colorspace. The array indices of the values property match the order of the colorspace.axes property of currently used detection profile.

transformed_color

values Array of number, minimum items: 3, maximum items: 3, required	Location in a colorspace

representations

ColorRepresentations, required

Pre-calculcated visual representations of a color suitable for rendering

representations

RGB Array of number, minimum items: 3, maximum items: 3, required	RGB color array representing the axes r, g, and b in that order. Values are floats between 0 and 1.

inputs

InputsState, required

The state of all inputs during a given period is specified by a list of possible events combined with a boolean value indicating, if the given event occurred within the period.

inputs

// boolean, required	The boolean value indicates whether the named input event occurred during the last period.

detection

ColorMatchingResult, required

detection

matcher

any of UUID (string) or null, optional, Deprecated

Deprecated: use "chosen_matcher_id" instead

chosen_matcher_id

any of UUID (string) or null, required

unique identifier of the selected matcher

distances

Array of any of number or null, required

Distance between the sample's color position and the selected matcher's closest color position along the three axes of the color space.

The array contains three 'null' values, if no suitable matcher was found for the current color sample.

output_pattern

CurrentSwitchingOutputsState, required

output_pattern

states Array of any of boolean or null, required	List of True/False values describing the current states of the Switching Outputs

signal_level

number, required

The signal level indicates the usage of the internal ADC sampling range. This

ActionResultTeachDetectable

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

alias

Alias (integer), required, read-only

matcher_id

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

reference to the Matcher containing this Detectable

color

TransformedColor, required

A color represented by a coordinate in the colorspace. The array indices of the values property match the order of the colorspace.axes property of currently used detection profile.

color

values Array of number, minimum items: 3, maximum items: 3, required	Location in a colorspace

representations

ColorRepresentations, optional, read-only

Pre-calculcated visual representations of a color suitable for rendering

representations

RGB Array of number, minimum items: 3, maximum items: 3, required	RGB color array representing the axes r, g, and b in that order. Values are floats between 0 and 1.

ActionResultKeyLock

locked boolean, required	New state of the keypad locking.

ActionResultRunAutogain

level number , default: `0.8`, minimum: 0.01, maximum: 1, optional	Target value for the auto-gain procedure
minimum_sample_rate SampleRate, minimum: 0.01, optional	Desired sample rate (the default is the current sample rate)
enable_internal_emitter boolean , default: `true`, optional	controls the power of the internal light source
enable_ambient_light_compensation boolean , default: `true`, optional	Control the ambient light compensation procedure. This setting is only relevant if `enable_internal_emitter` is set to true. The ambient light compensation leads to a pulsed usage of the internal light emitter. Samples are collected for alternating light and dark phases. This allows to calculate a color sample of the target excluding any optical interference from external light sources. You should not disable ambient light compensation unless the optical path is perfectly isolated. Otherwise external light will inevitably interfere with the color sampling.
averages AverageSampleCount, minimum: 1, optional	Number of previous samples to be averaged for every sampling result. A rolling averaging algorithm is applied to the samples.

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

The empty response indicates success

Defaults

Collection of defaults and settings for specific tasks. Apart from the custom user-defined values this API also returns factory defaults. Defaults are implicitly applied during specific actions like the creation of matchers or when executing certain behaviours.

Client applications can use this API endpoint to store settings that are independent from their current session or the client itself. Type and validation checks are the responsibility of the client application.

Be aware that defaults may be applied at runtime (like the creation of a matcher) and thus an invalid default value will break the application at a later point in time. Mind the notes below to prevent such problems when operating with the defaults API.

Default values are not subject to any kind of validation, but are handled as raw data. An invalid hold_time (negative, string instead of a number) for a matcher will become effective during the creation of a new matcher and only if the request for creating the matcher did not contain a hold_time field. In such a case the creation of a matcher would fail. It is therefore paramount to properly validate default values.
The fields object_type and key are yours to choose. This allows applications to store session- and client-independent data (e.g. an interface theme, color scheme, etc.). In order to avoid name-collisions with internal default-fields you should prefix the object_type or key field with x- (e.g. x-theme instead of theme). The API will never use fields internally that start with x-.
The API resolves defaults with the following steps. Applications should implement the same behaviour, when resolving default values:
1. Check if an element in the defaults collection matches both object_type and key
2. In case it does: use this value
3. In case it does not: use the value from factory_defaults

Retrieve DefaultsMapValues ¶
GET /defaults

Returns two collections of DefaultsMapValue objects. defaults contains all custom defaults and factory_defaults all those that are part of the factory settings. The latter can’t be changed but custom defaults take precedence over factory defaults.

Response

Body

application/json

Properties (object)

data

object, required

data

defaults

Array of DefaultsMapValue, required

DefaultsMapValue[]

uuid UUID (string), pattern: `^[a-f0-9-]+$`, required, read-only	unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8
object_type string, required, read-only	Name of the object the default is meant for
key string, required, read-only	name of the object’s property
value any, required	Actual default value for the object’s property

factory_defaults

Array of DefaultsMapValue, required

DefaultsMapValue[]

uuid UUID (string), pattern: `^[a-f0-9-]+$`, required, read-only	unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8
object_type string, required, read-only	Name of the object the default is meant for
key string, required, read-only	name of the object’s property
value any, required	Actual default value for the object’s property

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Create DefaultsMapValues ¶
POST /defaults

All valid attributes for a PUT request of a defaults object are allowed. The attributes object_type, key and value are required. The API ensures that only one combination of object_type and key is present at a time. A POST request therefore doesn’t necessarily increase the number of elements in the collection.

Request

Body

application/json

Properties (DefaultsMapValue)

uuid UUID (string), pattern: `^[a-f0-9-]+$`, required, read-only	unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8
object_type string, required, read-only	Name of the object the default is meant for
key string, required, read-only	name of the object’s property
value any, required	Actual default value for the object’s property

Matcher: Tolerance

{
  "uuid": "a7bd36b3-e9c1-4f60-8d7e-cf47634a28b1",
  "object_type": "matcher",
  "key": "tolerance",
  "value": {
    "shape": "sphere",
    "limits": {
      "radius": 4
    }
  }
}

Matcher: Hold Time

{
  "uuid": "55b35901-1ea6-4b3d-864a-60af15a9b0c5",
  "object_type": "matcher",
  "key": "hold_time",
  "value": 0
}

Matcher: reset output after Hold Time expiry

{
  "uuid": "9ba8a7a4-7fa5-4bfc-8883-98d7b6084e91",
  "object_type": "matcher",
  "key": "reset_output_after_hold_time_expired",
  "value": false
}

Autogain: number of samples used for averaging

{
  "uuid": "eeb46031-10e5-4f13-901a-c7eb16aa0cf9",
  "object_type": "autogain",
  "key": "averages",
  "value": 0
}

Response

Body

application/json

Properties (object)

data

DefaultsMapValue, required

DefaultsMapValue

uuid UUID (string), pattern: `^[a-f0-9-]+$`, required, read-only	unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8
object_type string, required, read-only	Name of the object the default is meant for
key string, required, read-only	name of the object’s property
value any, required	Actual default value for the object’s property

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.validation.collection_size_exceeded

Input validation failed

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.validation.collection_size_exceeded

Remove multiple or all DefaultsMapValues ¶
DELETE /defaults

Remove a selection of DefaultsMapValues either based on a given filter argument (if supported for this collection) or remove all DefaultsMapValues from the collection.

Response

The empty response indicates success

Modify DefaultsMapValue ¶
PUT /defaults/{itemId} Permission Scope settings

Modify the default’s value. The fields uuid, object_type and key are invariable.

Request

Path Variables

itemId string, required

Body

application/json

Properties (DefaultsMapValue)

uuid UUID (string), pattern: `^[a-f0-9-]+$`, required, read-only	unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8
object_type string, required, read-only	Name of the object the default is meant for
key string, required, read-only	name of the object’s property
value any, required	Actual default value for the object’s property

Matcher: Tolerance

{
  "uuid": "a7bd36b3-e9c1-4f60-8d7e-cf47634a28b1",
  "object_type": "matcher",
  "key": "tolerance",
  "value": {
    "shape": "sphere",
    "limits": {
      "radius": 4
    }
  }
}

Matcher: Hold Time

{
  "uuid": "55b35901-1ea6-4b3d-864a-60af15a9b0c5",
  "object_type": "matcher",
  "key": "hold_time",
  "value": 0
}

Matcher: reset output after Hold Time expiry

{
  "uuid": "9ba8a7a4-7fa5-4bfc-8883-98d7b6084e91",
  "object_type": "matcher",
  "key": "reset_output_after_hold_time_expired",
  "value": false
}

Autogain: number of samples used for averaging

{
  "uuid": "eeb46031-10e5-4f13-901a-c7eb16aa0cf9",
  "object_type": "autogain",
  "key": "averages",
  "value": 0
}

Response

Body

application/json

Properties (object)

data

DefaultsMapValue, required

DefaultsMapValue

uuid UUID (string), pattern: `^[a-f0-9-]+$`, required, read-only	unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8
object_type string, required, read-only	Name of the object the default is meant for
key string, required, read-only	name of the object’s property
value any, required	Actual default value for the object’s property

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.not_found.collection.item

Input validation failed

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.not_found.collection.item

Item not found

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.not_found.collection.item

Delete DefaultsMapValue ¶
DELETE /defaults/{itemId} Permission Scope settings

Deletes a single DefaultsMapValue

Request

Path Variables

itemId string, required

Response

The empty response indicates success

May return the following error codes

LPLC.not_found.collection.item

Get DefaultsMapValue ¶
GET /defaults/{itemId} Permission Scope settings

Returns a single DefaultsMapValue

Request

Path Variables

itemId string, required

Response

Body

application/json

Properties (object)

data

DefaultsMapValue, required

DefaultsMapValue

uuid UUID (string), pattern: `^[a-f0-9-]+$`, required, read-only	unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8
object_type string, required, read-only	Name of the object the default is meant for
key string, required, read-only	name of the object’s property
value any, required	Actual default value for the object’s property

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.not_found.collection.item

Firmware

The firmware is stored on the device and controls all of its aspects. It can be upgraded and safely be reset to the factory defaults.

Get Firmware Information ¶
GET /firmware

Returns information about the currently running firmware.

Response

Body

application/json

Properties (object)

data

FirmwareInformation, required

Information describing a firmware version.

FirmwareInformation

id FirmwareBuildId (string), pattern: `^[a-f0-9]+$`, required	unique ID of the currently running firmware image
channel ReleaseChannel (string), one of [`stable`, `feature`] , default: `stable`, required	Describes the kind of a publication Releases on the `stable` channel are generally considered well-tested and are recommended for use in production. Releases on the `feature` add new features but haven’t been tested as much as a stable release. Feature releases can but should only be used in production with careful consideration.
created_on Timestamp (string), required	time this firmware build was created
name string, required	human-readable name of this release
notes string, required	Release notes formatted as markdown
version FirmwareVersion (string), required	version of a firmware
works_with Array of string, required	compatible device models (see `model_key` in `/api/device`)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Firmware Image Uploads ¶
GET /firmware/images Permission Scope system

Returns the list of all active partial or complete firmware uploads.

Response

Body

application/json

Properties (object)

data

Array of FirmwareImageUpload, required

FirmwareImageUpload[]

uuid UUID (string), pattern: `^[a-f0-9-]+$`, required, read-only	Unique ID of a firmware upload
build_id HashDigest (string), pattern: `^[a-f0-9]+$`, required	unique ID of the currently running firmware image
status string, one of [`incomplete`, `complete`, `invalid_signature`, `processing_failure`, `malformed_content`, `device_mismatch`], required	Current status of the firmware upload incomplete the number of bytes received is lower than the number of bytes that have been announced complete the firmware upload is complete and the new firmware can be applied invalid_signature the firmware checksum didn’t match the expected value processing_failure an internal undefined error occurred while processing the firmware malformed_content the uploaded firmware image uses an unexpected format or misses essential information device_mismatch the firmware image can not be applied to this device
uploaded_size integer, minimum: 0, required	number of uploaded bytes
expected_size integer, minimum: 1, required	expected total number of bytes for the firmware image
max_chunk_size integer, minimum: 1, required	maximum size for a data chunk uploaded to the device

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Upload Firmware ¶
POST /firmware/images Permission Scope system

Upload a new firmware for an upgrade in separate chunks or as a single form-based file upload.

Firmware Upload methods

Two different approaches are available for the upload of a firmware image. The client selects the wanted method by using the associated request format:

* `multipart` format: Upload the complete image in a single request.
* `JSON` body: Successively upload single blocks of the firmware image.

File-based upload ("multipart")

The file based approach is simple to use and preferable for most situations. It requires the use of the multipart/form-data request format. The request transmits the full firmware image file to the API. The API's response to this request is emitted as soon as all related operations are finished.

The request format multipart/form-data is commonly used for file based HTML forms. Thus it is also possible to use this firmware upload method with a simple HTML form even without any client side code.

Chunk-based upload (JSON body)

The chunk based approach requires more effort on the client side. This approach may be helpful if you want to achieve advanced flow control or status indications during the firmware upload. Use a JSON formatted request body if you want to use this method.

The initial POST request creates and returns a firmware upload entity (FirmwareImageUpload). You may use its UUID for uploading the chunks of the firmware image via subsequent POST requests to /api/firmware/images/UPLOAD_UUID/upload. The firmware upload can be finalized and applied by a POST request to /api/firmware/images/UPLOAD_UUID/apply.

Error handling

In case of an non-recoverable error the API will return a 400 (Bad Request) HTTP status code as early as possible. If the apply parameter has been set to a positive value the status code will be 424 (Failed Dependency).

Request

Body

multipart/form-data
application/json

Properties (object)

firmware_file FirmwareImageFile (file), required	The actual binary firmware image file. Please note that a `filename` (with an arbitrary value) needs to be supplied (in technical terms: the `Content-Disposition` header of this part of the request needs to have a `name` and a `filename` field).
apply integer, one of [`0`, `1`] , default: `0`, required	Whether to apply the firmware once it has been received and validated. If this field is set to `1` the firmware will be applied at once, otherwise the API returns the firmware details to allow the application to send a separate request to apply the firmware.

Properties (object)

build_id FirmwareBuildId (string), pattern: `^[a-f0-9]+$`, required	unique ID of the currently running firmware image
expected_size FirmwareImageSize (integer), minimum: 1, maximum: 1073741824, required	size of the firmware image in bytes

Response

Body

application/json

Properties (object)

data

FirmwareImageUpload, required

A fully or partially uploaded firmware image to be used for upgrading the firmware

FirmwareImageUpload

uuid UUID (string), pattern: `^[a-f0-9-]+$`, required, read-only	Unique ID of a firmware upload
build_id HashDigest (string), pattern: `^[a-f0-9]+$`, required	unique ID of the currently running firmware image
status string, one of [`incomplete`, `complete`, `invalid_signature`, `processing_failure`, `malformed_content`, `device_mismatch`], required	Current status of the firmware upload incomplete the number of bytes received is lower than the number of bytes that have been announced complete the firmware upload is complete and the new firmware can be applied invalid_signature the firmware checksum didn’t match the expected value processing_failure an internal undefined error occurred while processing the firmware malformed_content the uploaded firmware image uses an unexpected format or misses essential information device_mismatch the firmware image can not be applied to this device
uploaded_size integer, minimum: 0, required	number of uploaded bytes
expected_size integer, minimum: 1, required	expected total number of bytes for the firmware image
max_chunk_size integer, minimum: 1, required	maximum size for a data chunk uploaded to the device

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.validation.missing_input
LPLC.validation.string
LPLC.validation.non_negative_integer
LPLC.validation.positive_integer
LPLC.validation.smaller_integer
LPLC.format.malformed.upload
LPLC.internal_error

Input validation failed

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.validation.missing_input
LPLC.validation.string
LPLC.validation.non_negative_integer
LPLC.validation.positive_integer
LPLC.validation.smaller_integer
LPLC.format.malformed.upload
LPLC.internal_error

Failed to apply the uploaded image to this device

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.validation.missing_input
LPLC.validation.string
LPLC.validation.non_negative_integer
LPLC.validation.positive_integer
LPLC.validation.smaller_integer
LPLC.format.malformed.upload
LPLC.internal_error

Get firmware image upload ¶
GET /firmware/images/{itemId} Permission Scope system

Returns a single firmware image upload

Request

Path Variables

itemId string, required

Response

Body

application/json

Properties (object)

data

FirmwareImageUpload, required

A fully or partially uploaded firmware image to be used for upgrading the firmware

FirmwareImageUpload

uuid UUID (string), pattern: `^[a-f0-9-]+$`, required, read-only	Unique ID of a firmware upload
build_id HashDigest (string), pattern: `^[a-f0-9]+$`, required	unique ID of the currently running firmware image
status string, one of [`incomplete`, `complete`, `invalid_signature`, `processing_failure`, `malformed_content`, `device_mismatch`], required	Current status of the firmware upload incomplete the number of bytes received is lower than the number of bytes that have been announced complete the firmware upload is complete and the new firmware can be applied invalid_signature the firmware checksum didn’t match the expected value processing_failure an internal undefined error occurred while processing the firmware malformed_content the uploaded firmware image uses an unexpected format or misses essential information device_mismatch the firmware image can not be applied to this device
uploaded_size integer, minimum: 0, required	number of uploaded bytes
expected_size integer, minimum: 1, required	expected total number of bytes for the firmware image
max_chunk_size integer, minimum: 1, required	maximum size for a data chunk uploaded to the device

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.not_found.collection.item

Delete firmware image upload ¶
DELETE /firmware/images/{itemId} Permission Scope system

Deletes a single firmware image upload

Request

Path Variables

itemId string, required

Response

The empty response indicates success

May return the following error codes

LPLC.not_found.collection.item

Switch to new Firmware ¶
POST /firmware/images/{itemId}/apply Permission Scope system

Applies the firmware to the device thus overwriting the current system image followed by a reboot of the device.

Request

Path Variables

itemId string, required

Response

The empty response indicates success

May return the following error codes

LPLC.format.malformed.upload
LPLC.internal_error

Input validation failed

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.format.malformed.upload
LPLC.internal_error

Failed to apply the uploaded image to this device

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.format.malformed.upload
LPLC.internal_error

Internal server error

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.format.malformed.upload
LPLC.internal_error

Upload Chunk of Firmware ¶
POST /firmware/images/{itemId}/upload Permission Scope system

Uploads a data chunk (see max_chunk_size) for this firmware image. The Content-Range is send by the client and used by the server to determine where the chunk is inserted into the final image. Uploads must happen synchronous so that every chunks start address is defined as (last_chunk_end_address + 1).

New chunks can be uploaded as long as the firmware status is reported as incomplete. All other status indicate an either successful or defective firmware upload. In case of a permanent failure all subsequent chunk uploads will be terminated with a HTTP 400 (Bad Request) status code.

Request

Path Variables

itemId string, required

Request Headers

Content-Range string, pattern: `^bytes\s+\d+-\d+/\d+$`, required	Defines where the chunk is positioned in the firmware image file.

Response

The empty response indicates success

May return the following error codes

LPLC.format.malformed.upload
LPLC.header.content_range.conflicts
LPLC.header.content_range.invalid
LPLC.header.content_range.missing
LPLC.upload.missing_chunk
LPLC.upload.payload_too_big

Input validation failed

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.format.malformed.upload
LPLC.header.content_range.conflicts
LPLC.header.content_range.invalid
LPLC.header.content_range.missing
LPLC.upload.missing_chunk
LPLC.upload.payload_too_big

Get Recovery Firmware Information ¶
GET /firmware/recovery Permission Scope system

Returns information about the current recovery firmware.

Response

Body

application/json

Properties (object)

data

FirmwareInformation, required

Information describing a firmware version.

FirmwareInformation

id FirmwareBuildId (string), pattern: `^[a-f0-9]+$`, required	unique ID of the currently running firmware image
channel ReleaseChannel (string), one of [`stable`, `feature`] , default: `stable`, required	Describes the kind of a publication Releases on the `stable` channel are generally considered well-tested and are recommended for use in production. Releases on the `feature` add new features but haven’t been tested as much as a stable release. Feature releases can but should only be used in production with careful consideration.
created_on Timestamp (string), required	time this firmware build was created
name string, required	human-readable name of this release
notes string, required	Release notes formatted as markdown
version FirmwareVersion (string), required	version of a firmware
works_with Array of string, required	compatible device models (see `model_key` in `/api/device`)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Upgrade Recovery Firmware ¶
POST /firmware/recovery/upgrade-from-current Permission Scope system

Replaces the stored recovery image with the current system firmware. This is helpful in case you want to update the recovery image to a more recent version.

The factory image merely contains the actual firmware. It does not store the sensors configuration or settings.

The update process will take several minutes.

Response

The empty response indicates success

Internal server error

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Get Firmware Settings ¶
GET /firmware/settings Permission Scope system

Returns current settings regarding the firmware and possible upgrades.

Response

Body

application/json

Properties (object)

data

FirmwareSettings, required

Settings related to the device's firmware and upgrades.

FirmwareSettings

release_channel ReleaseChannel (string), one of [`stable`, `feature`] , default: `stable`, required	Describes the kind of a publication Releases on the `stable` channel are generally considered well-tested and are recommended for use in production. Releases on the `feature` add new features but haven’t been tested as much as a stable release. Feature releases can but should only be used in production with careful consideration.

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

/firmware/settings ¶
PUT /firmware/settings Permission Scope system

Request

Body

application/json

Properties (FirmwareSettings)

release_channel ReleaseChannel (string), one of [`stable`, `feature`] , default: `stable`, required	Describes the kind of a publication Releases on the `stable` channel are generally considered well-tested and are recommended for use in production. Releases on the `feature` add new features but haven’t been tested as much as a stable release. Feature releases can but should only be used in production with careful consideration.

Example
```
{
  "release_channel": "stable"
}
```

Response

Body

application/json

Properties (object)

data

FirmwareSettings, required

Settings related to the device's firmware and upgrades.

FirmwareSettings

release_channel ReleaseChannel (string), one of [`stable`, `feature`] , default: `stable`, required	Describes the kind of a publication Releases on the `stable` channel are generally considered well-tested and are recommended for use in production. Releases on the `feature` add new features but haven’t been tested as much as a stable release. Feature releases can but should only be used in production with careful consideration.

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.validation

Input validation failed

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.validation

Get Firmware Status ¶
GET /firmware/status Deprecated Permission Scope system

Returns information about the currently running firmware version.

Response

Body

application/json

Properties (object)

data

FirmwareRunningInformation, required

Information describing the currently running firmware.

FirmwareRunningInformation

build_id FirmwareBuildId (string), pattern: `^[a-f0-9]+$`, required	unique ID of the currently running firmware image
source_url any of string or null, optional	Absolute base URL of a firmware repository delivering firmware images suitable for this device
version FirmwareVersion (string), required	version of a firmware

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Access Control

Manage access to data and settings of the sensor.

Users

Users are the identities that are allowed to access the API.

A password is required for authenticating a user during login.

Roles

Roles describe a set of permissions. Each user may belong to multiple roles.

The role named anonymous is special: it cannot be assigned to users. Instead it describes the set of permissions that are granted to every unauthenticated as well as authenticated request. Thus this special role can be considered the minimum set of permissions that is open for everyone.

Evaluation of access permissions

All actions can be executed without authentication by default as long as no user account has been created.

If at least one user exists, access control is applied by the API. Thus permissions are checked before an incoming request is processed.

Authentication is conducted via the HTTP Basic Authentication Scheme.

Authorisation for a given action (e.g. view or edit) targeted at a specific API endpoint is verified as follows:

Which kind of action is requested by the user: view (GET) or edit (POST, PUT, DELETE)?
- Is this action currently configured to be forbidden? (see blocked_remote_actions)
To which access scope does the target API endpoint belong (e.g. network)?
Which roles are assigned to the authenticated user (e.g. operator)?
Does at least one of the permissions of any of these roles belong to the requested scope and contain the requested action?

The last of the questions above decides, whether a request is processed or rejected.

HTTP Responses

The following additional HTTP responses can be emitted while access control is active:

HTTP 401 Unauthorized: is returned if the request requires authentication, but no credentials were supplied or the given credentials were rejected (e.g. unknown user or wrong password). Web applications interfacing the API may want to use the X-WWW-Authenticate-Scheme-Disable header (see below) in order to prevent the user's browser from intercepting this error response.
HTTP 403 Forbidden: is returned if the given credentials were valid, but the associated user is not allowed to request the given action in the target scope. The 403 status may also be returned (with a different response payload), if the requested action is configured to be forbidden (see blocked_remote_actions). In this case the error code LPLC.access.blocked_remote_actions is returned in the response body.

The client may specify the X-WWW-Authenticate-Scheme-Disable HTTP header in any request. The content of this header is expected to be a comma-separated list of authentication schemes (see RFC 7235). These authentication schemes will not be advertised by the API as part of the WWW-Authenticate header in its response. The following example header content is suitable for preventing a browser from interfering with authentication related responses: -WWW-Authenticate-Scheme-Disable: Basic, Digest.

Inspect Access Control Scopes and Actions ¶
GET /access

Inspect the available aspects of the access control setup.

Response

Body

application/json

Properties (object)

data

AccessControlFeatures, required

AccessControlFeatures

blocked_remote_actions Array of AccessAction (string), required	Certain API actions (view, edit) can be forbidden. This field cannot be modified via remote API requests. Only local services (e.g. serial interface, Modbus, trigger input action) are allowed to change the content of this field. Please note, that the edit action does not implicitly include the view action. Thus in order to forbid any remote API access, both actions should be blocked.
actions Array of AccessAction (string), required	Available actions that can be allowed or denied via permissions.
scopes Array of AccessScope (string), required	Available scopes that can be accessed with the different actions.

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Change access control settings ¶
PUT /access

Change the available API actions (e.g. blocked_remote_actions).

Request

Body

application/json

Properties (AccessControlSettings)

blocked_remote_actions Array of AccessAction (string), required	Certain API actions (view, edit) can be forbidden. This field cannot be modified via remote API requests. Only local services (e.g. serial interface, Modbus, trigger input action) are allowed to change the content of this field. Please note, that the edit action does not implicitly include the view action. Thus in order to forbid any remote API access, both actions should be blocked.

Response

Body

application/json

Properties (object)

data

AccessControlFeatures, required

AccessControlFeatures

blocked_remote_actions Array of AccessAction (string), required	Certain API actions (view, edit) can be forbidden. This field cannot be modified via remote API requests. Only local services (e.g. serial interface, Modbus, trigger input action) are allowed to change the content of this field. Please note, that the edit action does not implicitly include the view action. Thus in order to forbid any remote API access, both actions should be blocked.
actions Array of AccessAction (string), required	Available actions that can be allowed or denied via permissions.
scopes Array of AccessScope (string), required	Available scopes that can be accessed with the different actions.

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Login into an account ¶
POST /access/login Permission Scope access

This endpoint can be used to create a session for the current user agent or testing credentials.

If the caller provided valid credentials and didn’t set the session_timeout to 0 the response will contain a Set-Cookie header that contains a session token used for future authentication and which is automatically handled by XMLHttpRequest and fetch.

Once a session token has been issued to the user agent any subsequent request to any of the API endpoints will reset the session timeout to the value provided by session_timeout as long as the session did not already expire at the point in time when the request was sent to the API. Therefore if the session timeout was set to 15 minutes and a request was made every 10 minutes the session would be valid indefinitely. This does not apply if the endpoint is explicitly excluded from resetting the session timeout (like GET /api/access/login).

To test credentials the client may send them along with session_timeout set to 0. The response status code will indicate if the credentials are valid but omits the Set-Cookie header thus retaining the currently used session token.

Be aware that the API may start to rate-limit the endpoint if too many invalid credentials have been send to it. Make sure that you implement some kind of user feedback in case of responses with HTTP status code 429 like deactivating the login form and/or displaying the remaining time until a new login may be attempted.

Request

Body

application/json

Properties (object)

username string, required	The name of the user that should be authenticated
password string, required	The password of the user that should be authenticated
session_timeout number , default: `1200`, optional	The lifetime of the session on the server-side in seconds. Passing `0` will prevent the API from setting the `Set-Cookie` header and allows for checking credentials without creating a new session.

Response

Authentication with the provided credentials was successful

Body

application/json

Properties (object)

data

LoginInformation, required

Describes the currently active login provided by the user agent

LoginInformation

logged_in_user

any of User or null, required

The currently logged in user. Is null if the credentials didn’t match any known user or have expired.

User

name string, pattern: `^[\w-]+$`, required, read-only	unique name identifying an account
password string, optional	Password assigned to this account (only writable; never returned in responses). Either a `password` or a `password_hash` needs to be supplied when creating a new user or changing a password.
password_hash HashDigest (string), pattern: `^[a-f0-9]+$`, optional	Password hash assigned to this account. Either a `password` or a `password_hash` needs to be supplied when creating a new user or changing a password.
roles Array of string, optional	The roles assigned to an account define its set of permissions.

session_timeout

any of number or null, required

Number of seconds this session has left before expiring. Is null if the provided credentials could not be matched to any active sessions, if the session expired or if the supplied authentication mechanism does not support sessions (e.g. HTTP Authentication).

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Authentication with the provided credentials failed

There were too many login requests and the user agent should wait for the amount of time specified in the Retry-After header.

Headers

Retry-After number, required	Number of seconds the user agent must wait before another request is sent to this endpoint.

Retrieve Information about the currently used Credentials ¶
GET /access/login A request to this endpoint does not reset the session timeout. Permission Scope access

Response

Body

application/json

Properties (object)

data

LoginInformation, required

Describes the currently active login provided by the user agent

LoginInformation

logged_in_user

any of User or null, required

The currently logged in user. Is null if the credentials didn’t match any known user or have expired.

User

name string, pattern: `^[\w-]+$`, required, read-only	unique name identifying an account
password string, optional	Password assigned to this account (only writable; never returned in responses). Either a `password` or a `password_hash` needs to be supplied when creating a new user or changing a password.
password_hash HashDigest (string), pattern: `^[a-f0-9]+$`, optional	Password hash assigned to this account. Either a `password` or a `password_hash` needs to be supplied when creating a new user or changing a password.
roles Array of string, optional	The roles assigned to an account define its set of permissions.

session_timeout

any of number or null, required

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Logout / Invalidate any current credentials ¶
DELETE /access/login Permission Scope access

Response

The provided credentials were successfully invalidated.

Could not invalidate the credentials. This is the case for any credentials that are not stateful or are handled on the client side like the Authorization Header used for HTTP Basic Authentication.

The endpoint was called without providing any kind of valid credentials. Thus no credentials were invalidated. Expired credentials are treated as invalid.

Create Users ¶
POST /access/users Permission Scope access

Create a new User

All supported data attributes in the body of the request are optional.

Request

Body

application/json

Properties (User)

name string, pattern: `^[\w-]+$`, required, read-only	unique name identifying an account
password string, optional	Password assigned to this account (only writable; never returned in responses). Either a `password` or a `password_hash` needs to be supplied when creating a new user or changing a password.
password_hash HashDigest (string), pattern: `^[a-f0-9]+$`, optional	Password hash assigned to this account. Either a `password` or a `password_hash` needs to be supplied when creating a new user or changing a password.
roles Array of string, optional	The roles assigned to an account define its set of permissions.

Example
```
{
  "name": "alice"
}
```

Response

Body

application/json

Properties (object)

data

User, required

User

name string, pattern: `^[\w-]+$`, required, read-only	unique name identifying an account
password string, optional	Password assigned to this account (only writable; never returned in responses). Either a `password` or a `password_hash` needs to be supplied when creating a new user or changing a password.
password_hash HashDigest (string), pattern: `^[a-f0-9]+$`, optional	Password hash assigned to this account. Either a `password` or a `password_hash` needs to be supplied when creating a new user or changing a password.
roles Array of string, optional	The roles assigned to an account define its set of permissions.

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.validation.collection_size_exceeded

Input validation failed

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.validation.collection_size_exceeded

Remove multiple or all Users ¶
DELETE /access/users Permission Scope access

Remove a selection of Users either based on a given filter argument (if supported for this collection) or remove all Users from the collection.

Response

The empty response indicates success

Retrieve Users ¶
GET /access/users Permission Scope access

Retrieves a list of available Users

Response

Body

application/json

Properties (object)

data

object, required

data

users

Array of User, required

User[]

name string, pattern: `^[\w-]+$`, required, read-only	unique name identifying an account
password string, optional	Password assigned to this account (only writable; never returned in responses). Either a `password` or a `password_hash` needs to be supplied when creating a new user or changing a password.
password_hash HashDigest (string), pattern: `^[a-f0-9]+$`, optional	Password hash assigned to this account. Either a `password` or a `password_hash` needs to be supplied when creating a new user or changing a password.
roles Array of string, optional	The roles assigned to an account define its set of permissions.

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Delete User ¶
DELETE /access/users/{name} Permission Scope access

Deletes a single User

Request

Path Variables

name string, required

Response

The empty response indicates success

May return the following error codes

LPLC.not_found.collection.item

Modify User ¶
PUT /access/users/{name} Permission Scope access

Modifies a single User

Request

Path Variables

name string, required

Body

application/json

Properties (User)

name string, pattern: `^[\w-]+$`, required, read-only	unique name identifying an account
password string, optional	Password assigned to this account (only writable; never returned in responses). Either a `password` or a `password_hash` needs to be supplied when creating a new user or changing a password.
password_hash HashDigest (string), pattern: `^[a-f0-9]+$`, optional	Password hash assigned to this account. Either a `password` or a `password_hash` needs to be supplied when creating a new user or changing a password.
roles Array of string, optional	The roles assigned to an account define its set of permissions.

Example
```
{
  "name": "alice"
}
```

Response

Body

application/json

Properties (object)

data

User, required

User

name string, pattern: `^[\w-]+$`, required, read-only	unique name identifying an account
password string, optional	Password assigned to this account (only writable; never returned in responses). Either a `password` or a `password_hash` needs to be supplied when creating a new user or changing a password.
password_hash HashDigest (string), pattern: `^[a-f0-9]+$`, optional	Password hash assigned to this account. Either a `password` or a `password_hash` needs to be supplied when creating a new user or changing a password.
roles Array of string, optional	The roles assigned to an account define its set of permissions.

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.not_found.collection.item

Input validation failed

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.not_found.collection.item

Item not found

Body

application/json

Properties (object)

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.not_found.collection.item

Get User ¶
GET /access/users/{name} Permission Scope access

Returns a single User

Request

Path Variables

name string, required

Response

Body

application/json

Properties (object)

data

User, required

User

name string, pattern: `^[\w-]+$`, required, read-only	unique name identifying an account
password string, optional	Password assigned to this account (only writable; never returned in responses). Either a `password` or a `password_hash` needs to be supplied when creating a new user or changing a password.
password_hash HashDigest (string), pattern: `^[a-f0-9]+$`, optional	Password hash assigned to this account. Either a `password` or a `password_hash` needs to be supplied when creating a new user or changing a password.
roles Array of string, optional	The roles assigned to an account define its set of permissions.

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

May return the following error codes

LPLC.not_found.collection.item

Retrieve AccessRoles ¶
GET /access/roles Permission Scope access

Retrieves a list of available AccessRoles

Response

Body

application/json

Properties (object)

data

object, required

data

roles

Array of AccessRole, required

AccessRole[]

string, required

permissions

Array of AccessPermission, required

AccessPermission[]

scope AccessScope (string), required	Every API endpoint belongs to an access control scope. A scope combined with a number of actions forms a permission.
actions Array of AccessAction (string), required

errors

Array of Error, required

Error[]

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

Type Reference

AccessAction ¶

Available actions that can be allowed or denied via permissions.

Type Information

AccessAction (string)

Read the status of the sensor and request sample data.
```
view
```
Change the status of the sensor and modify settings or detection details.
```
edit
```

AccessControlFeatures ¶

Properties

blocked_remote_actions Array of AccessAction (string), required	Certain API actions (view, edit) can be forbidden. This field cannot be modified via remote API requests. Only local services (e.g. serial interface, Modbus, trigger input action) are allowed to change the content of this field. Please note, that the edit action does not implicitly include the view action. Thus in order to forbid any remote API access, both actions should be blocked.
actions Array of AccessAction (string), required	Available actions that can be allowed or denied via permissions.
scopes Array of AccessScope (string), required	Available scopes that can be accessed with the different actions.

Example

{
  "actions": [
    "view",
    "edit"
  ],
  "blocked_remote_actions": [
    "edit"
  ],
  "scopes": [
    "access",
    "miscellaneous",
    "network",
    "notify",
    "peripherals",
    "sensor",
    "settings",
    "system"
  ]
}

AccessControlSettings ¶

Properties

blocked_remote_actions Array of AccessAction (string), required	Certain API actions (view, edit) can be forbidden. This field cannot be modified via remote API requests. Only local services (e.g. serial interface, Modbus, trigger input action) are allowed to change the content of this field. Please note, that the edit action does not implicitly include the view action. Thus in order to forbid any remote API access, both actions should be blocked.

AccessPermission ¶

A permission defines a set of allowed actions in a specific access control scope.

Properties

scope AccessScope (string), required	Every API endpoint belongs to an access control scope. A scope combined with a number of actions forms a permission.
actions Array of AccessAction (string), required

AccessRole ¶

A role describes a set of permissions. Each user may belong to multiple roles.

Properties

string, required

permissions

Array of AccessPermission, required

AccessPermission[]

scope AccessScope (string), required	Every API endpoint belongs to an access control scope. A scope combined with a number of actions forms a permission.
actions Array of AccessAction (string), required

AccessScope ¶

Every API endpoint belongs to an access control scope. A scope combined with a number of actions forms a permission.

Type Information

AccessScope (string)

Example
```
network
```

Action ¶

The sensor allows the connection of events with actions. Actions can be related to the sensor operations or the information handled by the sensor (e.g. the list of stored detectables).

The Action consists of a unique name and a set of optional arguments.

The list of available Actions and their possible arguments can be retrieved via /api/actions.

Properties

name string, required	Unique name of the action
arguments object, required	arguments

ActionAPIEditLock ¶

Change the locked state of API for write requests. This allows or disallows changing sensor settings via the API.

Properties

arguments

object, required

arguments

locked boolean, required	Target state of the API edit lock.

name

string, required

Unique name of the action

Example

{
  "name": "api_edit_lock",
  "arguments": {
    "locked": true
  }
}

ActionAPIViewLock ¶

Change the locked state of API for write requests. This allows or disallows reading the sensor state via the API.

Properties

arguments

object, required

arguments

locked boolean, required	Target state of the API view lock.

name

string, required

Unique name of the action

Example

{
  "name": "api_view_lock",
  "arguments": {
    "locked": true
  }
}

ActionEnableSwitchingOutput ¶

Apply the output_pattern of the currently detected matcher to the switching outputs of the sensor.

Properties

name string, required	Unique name of the action
arguments object, required	arguments

ActionKeyLock ¶

Change the locked state of the keypad. This allows or disallows local access to the sensor via the keypad.

Properties

arguments

object, required

arguments

locked boolean, required	Target state of the keypad locking.

name

string, required

Unique name of the action

Example

{
  "name": "keylock",
  "arguments": {
    "locked": true
  }
}

ActionRemoveAllDetectables ¶

Remove all stored Detectables belonging to any Matcher.

Properties

name string, required	Unique name of the action
arguments object, required	arguments

ActionRemoveAllMatchers ¶

Remove all stored Matchers (including the related detectables).

Properties

name string, required	Unique name of the action
arguments object, required	arguments

ActionResultEnableSwitchingOutput ¶

After each sampling period a Detection Result is determined based on the currently sampled color and the contents of the color storage (matchers and detectables).

In addition to the sampled color, the Detection Result includes transitions and events on all input lines during the last sample period, as well as the state of the switching outputs during the following sampling period.

Properties

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

timestamp

TimestampBackendUptime, required

The timestamp (given in microseconds) is based on the uptime of the internal analog sensor backend. It may get reset to zero under specific conditions.

corrected_color

CorrectedColor, required

Representation of a color in the colorspace XYZ.

corrected_color

values Array of number, minimum items: 3, maximum items: 3, required	Location in a colorspace

transformed_color

TransformedColor, required

A color represented by a coordinate in the colorspace. The array indices of the values property match the order of the colorspace.axes property of currently used detection profile.

transformed_color

values Array of number, minimum items: 3, maximum items: 3, required	Location in a colorspace

representations

ColorRepresentations, required

Pre-calculcated visual representations of a color suitable for rendering

representations

RGB Array of number, minimum items: 3, maximum items: 3, required	RGB color array representing the axes r, g, and b in that order. Values are floats between 0 and 1.

inputs

InputsState, required

The state of all inputs during a given period is specified by a list of possible events combined with a boolean value indicating, if the given event occurred within the period.

inputs

// boolean, required	The boolean value indicates whether the named input event occurred during the last period.

detection

ColorMatchingResult, required

detection

matcher

any of UUID (string) or null, optional

Deprecated: use "chosen_matcher_id" instead

chosen_matcher_id

any of UUID (string) or null, required

unique identifier of the selected matcher

distances

Array of any of number or null, required

Distance between the sample's color position and the selected matcher's closest color position along the three axes of the color space.

The array contains three 'null' values, if no suitable matcher was found for the current color sample.

output_pattern

CurrentSwitchingOutputsState, required

output_pattern

states Array of any of boolean or null, required	List of True/False values describing the current states of the Switching Outputs

signal_level

number, required

The signal level indicates the usage of the internal ADC sampling range. This

Example

{
  "uuid": "4575656f-efe4-4a7d-862c-9660c15cdf4e",
  "timestamp": 12455148861,
  "corrected_color": {
    "values": [
      0.419219434261322,
      0.4271118938922882,
      0.18753691017627716
    ]
  },
  "transformed_color": {
    "values": [
      78.10789489746094,
      5.271166801452637,
      -32.290863037109375
    ]
  },
  "representations": {
    "RGB": [
      0.6569499359485452,
      0.7560762577592035,
      0.9910401649653352
    ]
  },
  "inputs": {
    "trigger_0_level_low": true,
    "trigger_0_edge_falling": false,
    "trigger_0_edge_rising": false,
    "trigger_0_level_high": false
  },
  "detection": {
    "chosen_matcher_id": null,
    "distances": [
      null,
      null,
      null
    ],
    "output_pattern": {
      "states": [
        true,
        true,
        true
      ]
    }
  },
  "signal_level": 0.7
}

ActionResultKeyLock ¶

Properties

locked boolean, required	New state of the keypad locking.

Example
```
{
  "locked": true
}
```

ActionResultRemoveAllDetectables ¶

The response is empty and returns HTTP status 204.

Type Information

ActionResultRemoveAllDetectables (string)

ActionResultRemoveAllMatchers ¶

The response is empty and returns HTTP status 204.

Type Information

ActionResultRemoveAllMatchers (string)

ActionResultRunAutogain ¶

Optional settings for customizing the Autogain procedure.

Properties

level number , default: `0.8`, minimum: 0.01, maximum: 1, optional	Target value for the auto-gain procedure
minimum_sample_rate SampleRate, minimum: 0.01, optional	Desired sample rate (the default is the current sample rate)
enable_internal_emitter boolean , default: `true`, optional	controls the power of the internal light source
enable_ambient_light_compensation boolean , default: `true`, optional	Control the ambient light compensation procedure. This setting is only relevant if `enable_internal_emitter` is set to true. The ambient light compensation leads to a pulsed usage of the internal light emitter. Samples are collected for alternating light and dark phases. This allows to calculate a color sample of the target excluding any optical interference from external light sources. You should not disable ambient light compensation unless the optical path is perfectly isolated. Otherwise external light will inevitably interfere with the color sampling.
averages AverageSampleCount, minimum: 1, optional	Number of previous samples to be averaged for every sampling result. A rolling averaging algorithm is applied to the samples.

Example

{
  "level": 0.7,
  "minimum_sample_rate": 1500,
  "enable_internal_emitter": true,
  "enable_ambient_light_compensation": true
}

ActionResultTeachDetectable ¶

A detectable represents the numeric position in a colorspace. It is connected to a Matcher.

Properties

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

alias

Alias (integer), required

matcher_id

UUID (string), pattern: ^[a-f0-9-]+$, required

reference to the Matcher containing this Detectable

color

TransformedColor, required

A color represented by a coordinate in the colorspace. The array indices of the values property match the order of the colorspace.axes property of currently used detection profile.

color

values Array of number, minimum items: 3, maximum items: 3, required	Location in a colorspace

representations

ColorRepresentations, optional

Pre-calculcated visual representations of a color suitable for rendering

representations

RGB Array of number, minimum items: 3, maximum items: 3, required	RGB color array representing the axes r, g, and b in that order. Values are floats between 0 and 1.

Example

{
  "uuid": "9f968e8a-ad9c-45ce-9beb-a55011856a99",
  "alias": 2,
  "matcher_id": "1c7e9725-8753-4b6c-a0b7-a71d7e915cb5",
  "color": {
    "values": [
      0.476731,
      0.381263,
      0.128475
    ]
  },
  "representations": {
    "RGB": [
      0.396114,
      0.479113,
      0.552308
    ]
  }
}

ActionRunAutogain ¶

Start an automatic adjustment of the optiocal sensor setup. See /api/sensor/detection-profiles/current/autogain for details.

Properties

name string, required	Unique name of the action
arguments object, required	arguments

ActionSelectDetectionProfile ¶

Switch to a detection profile.

Properties

name string, required	Unique name of the action
arguments object, required	arguments

ActionTeachDetectable ¶

Add the currently sampled color as a Detectable to the selected matcher.

Properties

arguments

object, required

arguments

matcher_id

UUID (string), pattern: ^[a-f0-9-]+$, optional

The new Detectable is assigned to the Matcher identified by this UUID. In case this matcher UUID (and "matcher_output_pattern") is undefined, a new matcher is created.

matcher_output_pattern:

object, optional

matcher_output_pattern:

states Array of any of boolean or null, required	List of True/False values describing the wanted states of the Switching Outputs

remove_matcher_detectables_before

boolean , default: true, optional

Remove all Detectables belonging to the configured Matcher before attaching the new Detectable.

name

string, required

Unique name of the action

Example

{
  "name": "teach_single",
  "arguments": {
    "matcher_id": "3f26aff4-8650-42a0-b319-51776c443fbc",
    "remove_matcher_detectables_before": false
  }
}

ActionTrigger ¶

An Action Trigger assigns a given set of actions with an event.

At the end of each sample period, all events are evaluated. All corresponding actions are executed afterwards.

Properties

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

event

TriggerEventName (string), required

Any of the event names provided by /api/sensor/capabilities (attribute trigger_sources) is allowed.

actions

Array of Action, required

List of actions to be executed after the given event.

Action[]

name string, required	Unique name of the action
arguments object, required	arguments

Example

{
  "uuid": "3f26aff4-8650-42a0-b319-51776c443fbc",
  "event": "trigger_0_edge_falling",
  "actions": [
    {
      "name": "enable_switching_output",
      "arguments": {}
    }
  ]
}

Alias ¶

Type Information

Alias (integer)

Example
```
4
```

AmplificationLevel ¶

The amplification level specifies the internal configuration of an amplifier. This value is not meant to be manipulated by regular users. It should be handled as is (stored, transmitted and applied without modification or introspection).

Type Information

AmplificationLevel (integer)

AnyAction ¶

Type Information

any of ActionEnableSwitchingOutput, ActionTeachDetectable, ActionKeyLock, ActionAPIViewLock, ActionAPIEditLock, ActionRunAutogain, ActionRemoveAllDetectables, ActionRemoveAllMatchers or ActionSelectDetectionProfile

AnyActionResult ¶

Type Information

AutogainSettings ¶

Optional settings for customizing the Autogain procedure.

Properties

level number , default: `0.8`, minimum: 0.01, maximum: 1, optional	Target value for the auto-gain procedure
minimum_sample_rate SampleRate (number), minimum: 0.01, optional	Desired sample rate (the default is the current sample rate)
enable_internal_emitter boolean , default: `true`, optional	controls the power of the internal light source
enable_ambient_light_compensation boolean , default: `true`, optional	Control the ambient light compensation procedure. This setting is only relevant if `enable_internal_emitter` is set to true. The ambient light compensation leads to a pulsed usage of the internal light emitter. Samples are collected for alternating light and dark phases. This allows to calculate a color sample of the target excluding any optical interference from external light sources. You should not disable ambient light compensation unless the optical path is perfectly isolated. Otherwise external light will inevitably interfere with the color sampling.
averages AverageSampleCount (integer), minimum: 1, optional	Number of previous samples to be averaged for every sampling result. A rolling averaging algorithm is applied to the samples.

Example

{
  "level": 0.7,
  "minimum_sample_rate": 1500,
  "enable_internal_emitter": true,
  "enable_ambient_light_compensation": true
}

AverageSampleCount ¶

Number of previous samples to be averaged for every sampling result. A rolling averaging algorithm is applied to the samples.

Type Information

AverageSampleCount (integer), minimum: 1

BaseColorTolerance ¶

Properties

shape ToleranceShapeName (string), required	Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via `/api/sensor/capabilities`.
limits object, required	limits

BaseSerialSettings ¶

Properties

type string, one of [`eliza`, `modbus`, `nil`] , default: `eliza`, required

BoxColorTolerance ¶

Properties

limits

object, required

limits

half_edges Array of number, minimum items: 3, maximum items: 3, required

shape

ToleranceShapeName (string), required

Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via /api/sensor/capabilities.

ChromaticityCoordinate ¶

Location in a colorspace

Type Information

Array of number, minimum items: 3, maximum items: 3

ColorDetectable ¶

A detectable represents the numeric position in a colorspace. It is connected to a Matcher.

Properties

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

alias

Alias (integer), required, read-only

matcher_id

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

reference to the Matcher containing this Detectable

color

TransformedColor, required

A color represented by a coordinate in the colorspace. The array indices of the values property match the order of the colorspace.axes property of currently used detection profile.

color

values Array of number, minimum items: 3, maximum items: 3, required	Location in a colorspace

representations

ColorRepresentations, optional, read-only

Pre-calculcated visual representations of a color suitable for rendering

representations

RGB Array of number, minimum items: 3, maximum items: 3, required	RGB color array representing the axes r, g, and b in that order. Values are floats between 0 and 1.

Example

{
  "uuid": "9f968e8a-ad9c-45ce-9beb-a55011856a99",
  "alias": 2,
  "matcher_id": "1c7e9725-8753-4b6c-a0b7-a71d7e915cb5",
  "color": {
    "values": [
      0.476731,
      0.381263,
      0.128475
    ]
  },
  "representations": {
    "RGB": [
      0.396114,
      0.479113,
      0.552308
    ]
  }
}

ColorDetectionResult ¶

After each sampling period a Detection Result is determined based on the currently sampled color and the contents of the color storage (matchers and detectables).

Properties

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

timestamp

TimestampBackendUptime (number), required

The timestamp (given in microseconds) is based on the uptime of the internal analog sensor backend. It may get reset to zero under specific conditions.

corrected_color

CorrectedColor, required

Representation of a color in the colorspace XYZ.

corrected_color

values Array of number, minimum items: 3, maximum items: 3, required	Location in a colorspace

transformed_color

TransformedColor, required

A color represented by a coordinate in the colorspace. The array indices of the values property match the order of the colorspace.axes property of currently used detection profile.

transformed_color

values Array of number, minimum items: 3, maximum items: 3, required	Location in a colorspace

representations

ColorRepresentations, required

Pre-calculcated visual representations of a color suitable for rendering

representations

RGB Array of number, minimum items: 3, maximum items: 3, required	RGB color array representing the axes r, g, and b in that order. Values are floats between 0 and 1.

inputs

InputsState, required

The state of all inputs during a given period is specified by a list of possible events combined with a boolean value indicating, if the given event occurred within the period.

inputs

// boolean, required	The boolean value indicates whether the named input event occurred during the last period.

detection

ColorMatchingResult, required

detection

matcher

any of UUID (string) or null, optional

Deprecated: use "chosen_matcher_id" instead

chosen_matcher_id

any of UUID (string) or null, required

unique identifier of the selected matcher

distances

Array of any of number or null, required

Distance between the sample's color position and the selected matcher's closest color position along the three axes of the color space.

The array contains three 'null' values, if no suitable matcher was found for the current color sample.

output_pattern

CurrentSwitchingOutputsState, required

output_pattern

states Array of any of boolean or null, required	List of True/False values describing the current states of the Switching Outputs

signal_level

number, required

The signal level indicates the usage of the internal ADC sampling range. This

Example

{
  "uuid": "4575656f-efe4-4a7d-862c-9660c15cdf4e",
  "timestamp": 12455148861,
  "corrected_color": {
    "values": [
      0.419219434261322,
      0.4271118938922882,
      0.18753691017627716
    ]
  },
  "transformed_color": {
    "values": [
      78.10789489746094,
      5.271166801452637,
      -32.290863037109375
    ]
  },
  "representations": {
    "RGB": [
      0.6569499359485452,
      0.7560762577592035,
      0.9910401649653352
    ]
  },
  "inputs": {
    "trigger_0_level_low": true,
    "trigger_0_edge_falling": false,
    "trigger_0_edge_rising": false,
    "trigger_0_level_high": false
  },
  "detection": {
    "chosen_matcher_id": null,
    "distances": [
      null,
      null,
      null
    ],
    "output_pattern": {
      "states": [
        true,
        true,
        true
      ]
    }
  },
  "signal_level": 0.7
}

ColorDetectionResultList ¶

Type Information

Array of ColorDetectionResult

ColorDetectionResultOrNil ¶

Type Information

any of ColorDetectionResult or null

ColorMatcher ¶

A matcher represents a distinguished detection result and the wanted behaviour of the sensor whenever it is encountered.

Properties

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

alias

Alias (integer), required, read-only

name

string, required

human-readable name of the matcher

tolerance

any of InfiniteColorTolerance, SphereColorTolerance, CylinderColorTolerance or BoxColorTolerance, required

Specification of a geometric shape and its dimensions in the current colorspaces.

InfiniteColorTolerance

limits object, required	limits
shape ToleranceShapeName (string), required	Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via `/api/sensor/capabilities`.

SphereColorTolerance

limits

object, required

limits

radius number, required

shape

ToleranceShapeName (string), required

Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via /api/sensor/capabilities.

CylinderColorTolerance

limits

object, required

limits

radius number, required
half_height number, required

shape

ToleranceShapeName (string), required

Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via /api/sensor/capabilities.

BoxColorTolerance

limits

object, required

limits

half_edges Array of number, minimum items: 3, maximum items: 3, required

shape

ToleranceShapeName (string), required

Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via /api/sensor/capabilities.

output_pattern

WantedSwitchingOutputsState, required

The combination of tristate values describes a logical state of the switching outputs of the sensor.

The states true or false cause the output to go up or down. The state null keeps the previous state of the output unchanged.

output_pattern

uuid UUID (string), pattern: `^[a-f0-9-]+$`, required, read-only	unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8
states Array of any of boolean or null, required	List of True/False/Null values describing the wanted states of the Switching Outputs

hold_time

HoldTime (number), maximum: 3153600000, required

Minimum duration (in seconds) of a matcher's output setup being applied after detection.

reset_output_after_hold_time_expired

boolean , default: false, required

Controls if the output should be reset after the hold time passed. This is helpful if you only sample by triggering inputs and wish to reset the outputs afterwards.

signal_color

any of string or null, required

A custom color name. How and what color will be displayed is defined by the client.

Example

{
  "uuid": "9ffaa31f-8011-44f5-bb2a-f91e4be50764",
  "alias": 6,
  "name": "clean bottle cap",
  "tolerance": {
    "limits": {
      "radius": 2,
      "half_height": 4
    },
    "shape": "cylinder"
  },
  "output_pattern": {
    "uuid": "1adc74e2-96ac-4761-b9e6-2d93e02d9244",
    "states": [
      true,
      false,
      false
    ]
  },
  "hold_time": 0,
  "reset_output_after_hold_time_expired": false,
  "signal_color": null
}

ColorMatchingResult ¶

Properties

matcher

any of UUID (string) or null, optional

Deprecated: use "chosen_matcher_id" instead

chosen_matcher_id

any of UUID (string) or null, required

unique identifier of the selected matcher

distances

Array of any of number or null, required

Distance between the sample's color position and the selected matcher's closest color position along the three axes of the color space.

The array contains three 'null' values, if no suitable matcher was found for the current color sample.

output_pattern

CurrentSwitchingOutputsState, required

output_pattern

states Array of any of boolean or null, required	List of True/False values describing the current states of the Switching Outputs

No Match

{
  "chosen_matcher_id": null,
  "distances": [
    null,
    null,
    null
  ],
  "output_pattern": {
    "states": [
      true,
      true,
      true
    ]
  }
}

Suitable Match

{
  "chosen_matcher_id": "4575656f-efe4-4a7d-862c-9660c15cdf4e",
  "distances": [
    1.4,
    0.3,
    null
  ],
  "output_pattern": {
    "states": [
      true,
      false,
      true
    ]
  }
}

ColorRepresentations ¶

Pre-calculcated visual representations of a color suitable for rendering

Properties

RGB Array of number, minimum items: 3, maximum items: 3, required	RGB color array representing the axes r, g, and b in that order. Values are floats between 0 and 1.

Example

{
  "RGB": [
    0.3197475,
    0.754686,
    0.216748
  ]
}

Colorspace ¶

A colorspace describes the numeric conversion of colors under certain circumstances. Different standardized colorspaces are suitable for different detection tasks.

Properties

name

string, required

space_id

ColorspaceID, required

Unique name of a colorspace

axes

Array of ColorspaceAxis, minimum items: 3, maximum items: 3, required

ColorspaceAxis[]

id string, required	Unique name
label string, required	Human-readable name
minimum number, required	lowest expected value of a color along this axis under usual circumstances
maximum number, required	highest expected value of a color along this axis under usual circumstances

Example

{
  "name": "L*a*b*",
  "space_id": "Lab",
  "axes": [
    {
      "id": "L",
      "label": "L*",
      "minimum": 0,
      "maximum": 100
    },
    {
      "id": "a",
      "label": "a*",
      "minimum": -500,
      "maximum": 500
    },
    {
      "id": "b",
      "label": "b*",
      "minimum": -200,
      "maximum": 200
    }
  ]
}

ColorspaceAxis ¶

Properties

id string, required	Unique name
label string, required	Human-readable name
minimum number, required	lowest expected value of a color along this axis under usual circumstances
maximum number, required	highest expected value of a color along this axis under usual circumstances

ColorspaceID ¶

Unique name of a colorspace

Type Information

ColorspaceID (string)

ColorspaceToleranceMap ¶

Specify the usage of the axes of each colorspace for non-trivial tolerance shapes. See "colorspace_tolerance_maps" below "/capabilities" for more details.

Properties

colorspace_id

ColorspaceID (string), required

Unique name of a colorspace

tolerance_shape

ToleranceShapeName (string), required

Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via /api/sensor/capabilities.

limits_axes_map

object, required

limits_axes_map

half_height Array of string, optional
half_edges Array of string, optional
radius Array of string, optional

Example

{
  "colorspace_id": "Lab",
  "tolerance_shape": "cylindrical",
  "limits_axes_map": {
    "half_height": [
      "L"
    ],
    "radius": [
      "a",
      "b"
    ]
  }
}

ColorTolerance ¶

Specification of a geometric shape and its dimensions in the current colorspaces.

Type Information

any of InfiniteColorTolerance, SphereColorTolerance, CylinderColorTolerance or BoxColorTolerance

Infinite

{
  "shape": "infinite",
  "limits": {}
}

Sphere

{
  "shape": "sphere",
  "limits": {
    "radius": 2
  }
}

Cylinder

{
  "shape": "cylinder",
  "limits": {
    "radius": 2,
    "half_height": 4
  }
}

Box

{
  "shape": "box",
  "limits": {
    "half_edges": [
      4,
      2,
      2
    ]
  }
}

CompensationSettings ¶

The compensation settings of a Detection Profile describe the configuration of internal sensor components related to the stabilization and compensation algorithms.

The content of this data object is not meant to be manipulated by regular users. It should be handled as is (stored, transmitted and applied without modification or introspection).

CorrectedColor ¶

Representation of a color in the colorspace XYZ.

Properties

values Array of number, minimum items: 3, maximum items: 3, required	Location in a colorspace

CurrentDetectionProfileID ¶

Type Information

CurrentDetectionProfileID (string), pattern: ^[a-f0-9-]+$

Example
```
a014e415-0fec-4734-ac3f-30da0a5f3899
```

CurrentSwitchingOutputsState ¶

Properties

states Array of any of boolean or null, required	List of True/False values describing the current states of the Switching Outputs

CylinderColorTolerance ¶

Properties

limits

object, required

limits

radius number, required
half_height number, required

shape

ToleranceShapeName (string), required

Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via /api/sensor/capabilities.

DefaultsMapValue ¶

Properties

uuid UUID (string), pattern: `^[a-f0-9-]+$`, required, read-only	unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8
object_type string, required, read-only	Name of the object the default is meant for
key string, required, read-only	name of the object’s property
value any, required	Actual default value for the object’s property

Matcher: Tolerance

{
  "uuid": "a7bd36b3-e9c1-4f60-8d7e-cf47634a28b1",
  "object_type": "matcher",
  "key": "tolerance",
  "value": {
    "shape": "sphere",
    "limits": {
      "radius": 4
    }
  }
}

Matcher: Hold Time

{
  "uuid": "55b35901-1ea6-4b3d-864a-60af15a9b0c5",
  "object_type": "matcher",
  "key": "hold_time",
  "value": 0
}

Matcher: reset output after Hold Time expiry

{
  "uuid": "9ba8a7a4-7fa5-4bfc-8883-98d7b6084e91",
  "object_type": "matcher",
  "key": "reset_output_after_hold_time_expired",
  "value": false
}

Autogain: number of samples used for averaging

{
  "uuid": "eeb46031-10e5-4f13-901a-c7eb16aa0cf9",
  "object_type": "autogain",
  "key": "averages",
  "value": 0
}

DetectionProfile ¶

A Detection Profile contains a complete set of sensor settings for a given detection task.

Multiple profiles can be stored in order to switch easily between different detection task or for the incremental development of a refined profile.

Properties

uuid

UUID (string), pattern: ^[a-f0-9-]+$, required, read-only

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

alias

Alias (integer), required, read-only

name

string, required

Human-readable name of the Detection Profile

colorspace

Colorspace, required

A colorspace describes the numeric conversion of colors under certain circumstances. Different standardized colorspaces are suitable for different detection tasks.

colorspace

name

string, required

space_id

ColorspaceID, required

Unique name of a colorspace

axes

Array of ColorspaceAxis, minimum items: 3, maximum items: 3, required

ColorspaceAxis[]

id string, required	Unique name
label string, required	Human-readable name
minimum number, required	lowest expected value of a color along this axis under usual circumstances
maximum number, required	highest expected value of a color along this axis under usual circumstances

non_matching_output

WantedSwitchingOutputsState, required

This state of the Switching Outputs is applied, if the currently sample color does not belong to any of the stored Matchers.

non_matching_output

uuid UUID (string), pattern: `^[a-f0-9-]+$`, required, read-only	unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8
states Array of any of boolean or null, required	List of True/False/Null values describing the wanted states of the Switching Outputs

non_matching_hold_time

HoldTime (number), maximum: 3153600000, required

compensation_settings

CompensationSettings, required

The compensation settings of a Detection Profile describe the configuration of internal sensor components related to the stabilization and compensation algorithms.

The content of this data object is not meant to be manipulated by regular users. It should be handled as is (stored, transmitted and applied without modification or introspection).

compensation_settings

sampling_settings

SamplingSettings, required

Sampling Settings describe all details of the sampling process.

Its attributes may be queried and inspected (e.g. in order to retrieve the current sample rate).

Most values stored within the Sampling Settings should not be modified directly. The related API endpoint /api/sensor/detection-profiles/current/autogain should be used instead.

sampling_settings

led_intensity number, minimum: 0, maximum: 1, required	relative intensity of the internal emitter during the light phase
base_sample_rate SampleRate (number), minimum: 0.01, required	The base sample rate determines the duration of a sampling period. After each sampling period, the gathered data is processed and a new detection result is calculated (e.g. the most suitable Matcher for the given sample). This may affect the state of the Switching Outputs or trigger configured actions. Thus the base sample rate defines the maximum rate of changes for the Switching Outputs. See also the effective sample rate.
effective_sample_rate SampleRate (number), minimum: 0.01, required	The effective sample rate is the numeric product of the base sample rate and the number of averages. It determines the minimum duration that a target needs to be sampled in order to determine its visual appearance correctly. With the default value of average set to one, this value is equal to the base sample rate.
minimum_wanted_sample_rate SampleRate (number), minimum: 0.01, required	This informational value represents the sample rate that was requested during the most recent Autogain operation. The effective sample rate may deviate from the wanted sample rate, if the requested sample rate was not achievable due to limitations of the sensor (e.g. exceeding the supported sample rate) or due to the environment (e.g. not enough light, thus a slower amplification with higher gain was necessary).
sample_light_phase boolean, required	defines if the sensor should periodically activate the internal emitter for sampling
sample_dark_phase boolean, required	defines if the sensor should periodically deactivate the internal emitter for sampling
averages AverageSampleCount (integer), minimum: 1, required	Number of previous samples to be averaged for every sampling result. A rolling averaging algorithm is applied to the samples.
suppress_intermediate_averages SuppressIntermediateAverages (boolean), required	If set to True, then only one sample is emitted after the configured number of averages is processed. Otherwise all intermdiate results are emitted, too. This toggles the behaviour between moving averaging and block-based averaging. Switching outputs are updated less frequently, if intermediate averages are suppressed.
amplification AmplificationLevel (integer), required	The amplification level specifies the internal configuration of an amplifier. This value is not meant to be manipulated by regular users. It should be handled as is (stored, transmitted and applied without modification or introspection).

white_reference

Array of number, required

The White Reference attribute is used for indicating a custom color balancing.

Its content is subject to internal use. Thus it should not be accessed directly, but only through the related API endpoints (e.g. /api/sensor/detection-profiles/{itemId}/white-reference).

normalization_constant

Array of number, required

Normalization constants are related to the White Reference.

Its content is subject to internal use. Thus it should not be accessed directly, but only through the related API endpoints (e.g. /api/sensor/detection-profiles/{itemId}/white-reference).

Example

{
  "name": "#0",
  "uuid": "2475df8d-85f0-4208-ba60-dce6cb282a96",
  "alias": 1,
  "non_matching_hold_time": 0,
  "colorspace": {
    "name": "L*a*b*",
    "axes": [
      {
        "id": "L",
        "label": "L*",
        "minimum": 0,
        "maximum": 100
      },
      {
        "id": "a",
        "label": "a*",
        "minimum": -500,
        "maximum": 500
      },
      {
        "id": "b",
        "label": "b*",
        "minimum": -200,
        "maximum": 200
      }
    ],
    "space_id": "Lab"
  },
  "compensation_settings": {
    "monitor_integration": {
      "control": 0.32499998807907104,
      "references": [
        0.7283520102500916,
        0.7442666888237,
        0.7066696286201477
      ]
    },
    "use_calibration_samples": true
  },
  "normalization_constant": [
    237.4935277662995,
    242.62655153828055,
    587.8264132734112
  ],
  "white_reference": [
    95.047,
    100,
    108.883
  ],
  "non_matching_output": {
    "uuid": "3f26aff4-8650-42a0-b319-51776c443fbc",
    "states": [
      true,
      true,
      true,
      true,
      true,
      true,
      true,
      true
    ]
  },
  "sampling_settings": {
    "led_intensity": 1,
    "amplification": 1,
    "sample_light_phase": true,
    "minimum_wanted_sample_rate": 1000,
    "averages": 1,
    "suppress_intermediate_averages": false,
    "base_sample_rate": 1000,
    "sample_dark_phase": true,
    "effective_sample_rate": 1000
  }
}

DeviceInformation ¶

Properties

id DeviceSerialNumber, required	Serial Number
model_name string, required	human-readable name of the device model
model_key string, required	unique id of the device model
variant any of string or null, required	indicates a special series of a model
vendor_key DeviceVendorKey, required	Unique key identifying the organization distributing this device
vendor_name DeviceVendorName, required	Name of vendor of this device
device_id DeviceSerialNumber, optional, Deprecated	Deprecated: use "id" instead.
model string, optional, Deprecated	Deprecated: use "model_name" instead.
vendor DeviceVendorName, optional, Deprecated	Deprecated: use "vendor_name" instead.

Example

{
  "vendor_name": "Silicann Systems GmbH",
  "vendor_key": "silicann",
  "variant": null,
  "model_key": "blickwerk_10",
  "model_name": "Blickwerk 10",
  "id": "7454232361"
}

DeviceSerialNumber ¶

Serial Number

Type Information

DeviceSerialNumber (string)

DeviceVendorKey ¶

Unique key identifying the organization distributing this device

Type Information

DeviceVendorKey (string)

Example
```
acme
```

DeviceVendorName ¶

Name of vendor of this device

Type Information

DeviceVendorName (string)

Example
```
Acme Corporation
```

Error ¶

List of error indicators that are both machine-parseable and human-readable

Properties

code string, optional	machine-readable unique error code
mapping string, optional	a reference to the parameter that caused the error
message string, optional	human-readable error description

FirmwareBuildId ¶

unique ID of the currently running firmware image

Type Information

FirmwareBuildId (string), pattern: ^[a-f0-9]+$

Example
```
d985c28e03a4eb39132c02affeb29e71
```

FirmwareImageFile ¶

Type Information

FirmwareImageFile (file)

FirmwareImageSize ¶

size of the firmware image in bytes

Type Information

FirmwareImageSize (integer), minimum: 1, maximum: 1073741824

FirmwareImageUpload ¶

A fully or partially uploaded firmware image to be used for upgrading the firmware

Properties

uuid UUID (string), pattern: `^[a-f0-9-]+$`, required, read-only	Unique ID of a firmware upload
build_id HashDigest (string), pattern: `^[a-f0-9]+$`, required	unique ID of the currently running firmware image
status string, one of [`incomplete`, `complete`, `invalid_signature`, `processing_failure`, `malformed_content`, `device_mismatch`], required	Current status of the firmware upload incomplete the number of bytes received is lower than the number of bytes that have been announced complete the firmware upload is complete and the new firmware can be applied invalid_signature the firmware checksum didn’t match the expected value processing_failure an internal undefined error occurred while processing the firmware malformed_content the uploaded firmware image uses an unexpected format or misses essential information device_mismatch the firmware image can not be applied to this device
uploaded_size integer, minimum: 0, required	number of uploaded bytes
expected_size integer, minimum: 1, required	expected total number of bytes for the firmware image
max_chunk_size integer, minimum: 1, required	maximum size for a data chunk uploaded to the device

Example

{
  "uuid": "78b40d5e-e82c-45a9-8842-9481f889f790",
  "build_id": "e943ce84dbe474bc4d163b44c90070b105fd66bb",
  "expected_size": 335544320,
  "max_chunk_size": 1048576,
  "status": "incomplete",
  "uploaded_size": 24117248
}

FirmwareInformation ¶

Information describing a firmware version.

Properties

id FirmwareBuildId (string), pattern: `^[a-f0-9]+$`, required	unique ID of the currently running firmware image
channel ReleaseChannel (string), one of [`stable`, `feature`] , default: `stable`, required	Describes the kind of a publication Releases on the `stable` channel are generally considered well-tested and are recommended for use in production. Releases on the `feature` add new features but haven’t been tested as much as a stable release. Feature releases can but should only be used in production with careful consideration.
created_on Timestamp (string), required	time this firmware build was created
name string, required	human-readable name of this release
notes string, required	Release notes formatted as markdown
version FirmwareVersion (string), required	version of a firmware
works_with Array of string, required	compatible device models (see `model_key` in `/api/device`)

FirmwareRecoveryInformation ¶

Type Information

FirmwareRecoveryInformation (string)

Example

{
  "notes": "# Release 1.1.1 (2018-01-22 - blickwerk)\n\n## Veröffentlichungshinweise\n\n## Änderungen\n\n## Fehlerkorrekturen",
  "version": "1.1.1",
  "id": "e943ce84dbe474bc4d163b44c90070b105fd66bb",
  "name": "blickwerk",
  "created_on": "2018-01-24T14:04:26+01:00",
  "works_with": [
    "blickwerk_10",
    "blickwerk_20",
    "blickwerk_40"
  ],
  "channel": "stable"
}

FirmwareRunningInformation ¶

Information describing the currently running firmware.

Properties

build_id FirmwareBuildId (string), pattern: `^[a-f0-9]+$`, required	unique ID of the currently running firmware image
source_url any of string or null, optional	Absolute base URL of a firmware repository delivering firmware images suitable for this device
version FirmwareVersion (string), required	version of a firmware

Example

{
  "build_id": "4fab356b5014b5cc82efc4a81bfefbfcdc2d9165",
  "source_url": null,
  "version": "1.3.16"
}

FirmwareSettings ¶

Settings related to the device's firmware and upgrades.

Properties

release_channel ReleaseChannel (string), one of [`stable`, `feature`] , default: `stable`, required	Describes the kind of a publication Releases on the `stable` channel are generally considered well-tested and are recommended for use in production. Releases on the `feature` add new features but haven’t been tested as much as a stable release. Feature releases can but should only be used in production with careful consideration.

Example
```
{
  "release_channel": "stable"
}
```

FirmwareVersion ¶

version of a firmware

Type Information

FirmwareVersion (string)

Example
```
v2.3.42
```

HashDigest ¶

unique identifier (hexadecimal digest string)

Type Information

HashDigest (string), pattern: ^[a-f0-9]+$

Example
```
d985c28e03a4eb39132c02affeb29e71
```

HoldTime ¶

Minimum duration (in seconds) of a matcher's output setup being applied after detection.

Type Information

HoldTime (number), minimum: 0, maximum: 3153600000

Hostname ¶

Human-readable name identifying the device in the network

Type Information

Hostname (string), pattern: ^(?:[a-zA-Z0-9](?:[a-zA-Z0-9\-]*[a-zA-Z0-9])?\.)*[a-zA-Z0-9](?:[a-zA-Z0-9\-]*[a-zA-Z0-9])?$

InfiniteColorTolerance ¶

Properties

limits object, required	limits
shape ToleranceShapeName (string), required	Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via `/api/sensor/capabilities`.

InputsState ¶

The state of all inputs during a given period is specified by a list of possible events combined with a boolean value indicating, if the given event occurred within the period.

Properties

// boolean, required	The boolean value indicates whether the named input event occurred during the last period.

InterfaceRS232 ¶

Properties

protocol

any of SerialDisabledSettings, SerialModbusSettings or SerialElizaSettings, required

SerialDisabledSettings

type string, one of [`eliza`, `modbus`, `nil`] , default: `eliza`, required

SerialModbusSettings

type string, one of [`eliza`, `modbus`, `nil`] , default: `eliza`, required
slave_id any of number or null, required
frame_format string, one of [`rtu`, `ascii`] , default: `rtu`, required

SerialElizaSettings

type string, one of [`eliza`, `modbus`, `nil`] , default: `eliza`, required

supported_protocols

Array of string, optional, read-only

baud_rate

number, one of [9600, 19200, 115200], required

InterfaceUSB ¶

Properties

protocol

any of SerialDisabledSettings, SerialModbusSettings or SerialElizaSettings, required

SerialDisabledSettings

type string, one of [`eliza`, `modbus`, `nil`] , default: `eliza`, required

SerialModbusSettings

type string, one of [`eliza`, `modbus`, `nil`] , default: `eliza`, required
slave_id any of number or null, required
frame_format string, one of [`rtu`, `ascii`] , default: `rtu`, required

SerialElizaSettings

type string, one of [`eliza`, `modbus`, `nil`] , default: `eliza`, required

supported_protocols

Array of string, optional, read-only

KeypadEvent ¶

A keypad event represents a single press or release event of a button at a specific time.

Properties

source string, required	The usual source of events is inputs.
name KeypadEventInput (string), required	Name of a keypad input (button) that may trigger events.
event KeypadEventName (string), required	Input peripherals can trigger different events.
timestamp integer, minimum: 0, required	The timestamp is given in milliseconds and should be monotonic increasing.

Intensity Button pressed

{
  "source": "inputs",
  "name": "intensity",
  "event": "down",
  "timestamp": 6403500
}

Intensity Button released

{
  "source": "inputs",
  "name": "intensity",
  "event": "up",
  "timestamp": 6405800
}

KeypadEventInput ¶

Name of a keypad input (button) that may trigger events.

Type Information

KeypadEventInput (string)

KeypadEventName ¶

Input peripherals can trigger different events.

Type Information

KeypadEventName (string)

KeypadIndicator ¶

The keypad features multiple LEDs as visual indicators.

The indicators may be lit, blinking or off.

Properties

name

string, required

Name of the indicator

type

string, required

The type describes the possible modes of visualization for this indicator.

animation

Array of object, required

The visual state of each indicator is described by an infinite loop of animation steps.

object[]

enabled boolean, required	Visual status of the indicator (on or off)
color string, optional	Name or description of a color
duration number, required	Duration (in seconds) of this part of the looping animation.

Example

{
  "name": "trigger_teach",
  "type": "colored",
  "animation": [
    {
      "enabled": true,
      "color": "green",
      "duration": 0.6
    },
    {
      "enabled": false,
      "duration": 0.4
    }
  ]
}

KeypadInformation ¶

Describe the current state of the keypad as well as access to visualization data.

Properties

locked boolean, required	Boolean flag indicating the state of the key lock (true -> locked, false -> unlocked). All keypad inputs are ignored while the lock is active.
clear_matcher_before_teach boolean, required	The boolean flag controls whether multiple detectables can be stored for a matcher via keypad-based teach operations. A value of true implies, that a teach operation always removes all existing detectables from the currently selected matcher before adding the new detectable. With a value of false previously existing detectables are not deleted before a new one is added.
visualization_url any of string or null, optional, read-only	The visualization resource location can be used for providing a virtual keypad interface. Its URL may start with a scheme (e.g. http or https) for a full URL including hostname or it may start with a slash, indicating a path provided by the device itself. This attribute cannot be modified.

Example

{
  "locked": true,
  "clear_matcher_before_teach": false,
  "visualization_url": "/media/keypad-image.svg"
}

KeypadInputButton ¶

The keypad contains several inputs (buttons) that may generate events.

Properties

name

KeypadEventInput (string), required

Name of a keypad input (button) that may trigger events.

capabilities

Array of object, required

object[]

name KeypadEventName (string), required	Input peripherals can trigger different events.
url string, required	The event can be triggered externally by submitting a POST request against this resource.

Example

{
  "name": "intensity",
  "capabilities": [
    {
      "name": "down",
      "url": "/api/peripherals/keypad/inputs/intensity/down"
    },
    {
      "name": "up",
      "url": "/api/peripherals/keypad/inputs/intensity/up"
    }
  ]
}

LoginInformation ¶

Describes the currently active login provided by the user agent

Properties

logged_in_user

any of User or null, required

The currently logged in user. Is null if the credentials didn’t match any known user or have expired.

User

name string, pattern: `^[\w-]+$`, required, read-only	unique name identifying an account
password string, optional	Password assigned to this account (only writable; never returned in responses). Either a `password` or a `password_hash` needs to be supplied when creating a new user or changing a password.
password_hash HashDigest (string), pattern: `^[a-f0-9]+$`, optional	Password hash assigned to this account. Either a `password` or a `password_hash` needs to be supplied when creating a new user or changing a password.
roles Array of string, optional	The roles assigned to an account define its set of permissions.

session_timeout

any of number or null, required

MacAddress ¶

unique hardware address of a network interface

Type Information

MacAddress (string), pattern: ^([a-f0-9]{2}:){5}[a-f0-9]{2}$

Example
```
00:01:2e:7a:dc:23
```

NetworkAddressConfigurationIPv4 ¶

Properties

method string, one of [`static`, `dhcp`], required	Configuration method used for the address.

NetworkAddressConfigurationIPv4DHCP ¶

The Dynamic Host Configuration Protocol requires a router distributing leases on request.

Properties

method string, one of [`static`, `dhcp`], required	Configuration method used for the address.

NetworkAddressConfigurationIPv4Static ¶

Static address configuration does not depend on network infrastructure.

Properties

method string, one of [`static`, `dhcp`], required	Configuration method used for the address.
address NetworkInterfaceAddressIPv4 (string), required	IPv4 network address in CIDR notation
gateway NetworkAddressIPv4 (string), optional	default gateway for outgoing traffic

NetworkAddressConfigurationIPv6 ¶

Properties

method string, one of [`static`, `dhcp`, `auto`], required	Configuration method used for the address.

NetworkAddressConfigurationIPv6Auto ¶

Stateless address autoconfiguration (SLAAC) solely relies on the Neighbourhood Discovery Protocol. SLAAC is only available for IPv6.

Properties

method string, one of [`static`, `dhcp`, `auto`], required	Configuration method used for the address.

NetworkAddressConfigurationIPv6DHCP ¶

The Dynamic Host Configuration Protocol requires a router distributing leases on request.

Properties

method string, one of [`static`, `dhcp`, `auto`], required	Configuration method used for the address.

NetworkAddressConfigurationIPv6Static ¶

Static address configuration does not depend on network infrastructure.

Properties

method string, one of [`static`, `dhcp`, `auto`], required	Configuration method used for the address.
address NetworkInterfaceAddressIPv6 (string), required	IPv6 network address in CIDR notation
gateway NetworkAddressIPv6 (string), optional	default gateway for outgoing traffic

NetworkAddressIPv4 ¶

Type Information

NetworkAddressIPv4 (string)

Example
```
192.168.1.100
```

NetworkAddressIPv6 ¶

Type Information

NetworkAddressIPv6 (string)

Example
```
fda0:576b:c643:100:40f:10ff:fe02:e6f
```

NetworkInterfaceAddressConfigurationInformation ¶

Properties

ipv4

NetworkInterfaceAddressFamilyInformationIPv4, required

IPv4 Network address configuration

ipv4

address_configurations

Array of any of NetworkAddressConfigurationIPv4Static or NetworkAddressConfigurationIPv4DHCP, optional

NetworkAddressConfigurationIPv4Static[]

method string, one of [`static`, `dhcp`], required	Configuration method used for the address.
address NetworkInterfaceAddressIPv4 (string), required	IPv4 network address in CIDR notation
gateway NetworkAddressIPv4 (string), optional	default gateway for outgoing traffic

NetworkAddressConfigurationIPv4DHCP[]

method string, one of [`static`, `dhcp`], required	Configuration method used for the address.

current_addresses

Array of WrappedNetworkInterfaceAddressIPv4, required

WrappedNetworkInterfaceAddressIPv4[]

address NetworkInterfaceAddressIPv4 (string), required	IPv4 network address in CIDR notation

ipv6

NetworkInterfaceAddressFamilyInformationIPv6, required

IPv6 Network address configuration

ipv6

address_configurations

Array of any of NetworkAddressConfigurationIPv6Static, NetworkAddressConfigurationIPv6DHCP or NetworkAddressConfigurationIPv6Auto, optional

NetworkAddressConfigurationIPv6Static[]

method string, one of [`static`, `dhcp`, `auto`], required	Configuration method used for the address.
address NetworkInterfaceAddressIPv6 (string), required	IPv6 network address in CIDR notation
gateway NetworkAddressIPv6 (string), optional	default gateway for outgoing traffic

NetworkAddressConfigurationIPv6DHCP[]

method string, one of [`static`, `dhcp`, `auto`], required	Configuration method used for the address.

NetworkAddressConfigurationIPv6Auto[]

method string, one of [`static`, `dhcp`, `auto`], required	Configuration method used for the address.

current_addresses

Array of WrappedNetworkInterfaceAddressIPv6, required

WrappedNetworkInterfaceAddressIPv6[]

address NetworkInterfaceAddressIPv6 (string), required	IPv6 network address in CIDR notation

NetworkInterfaceAddressConfigurationIPv4 ¶

Type Information

Array of any of NetworkAddressConfigurationIPv4Static or NetworkAddressConfigurationIPv4DHCP

NetworkInterfaceAddressConfigurationIPv6 ¶

Type Information

Array of any of NetworkAddressConfigurationIPv6Static, NetworkAddressConfigurationIPv6DHCP or NetworkAddressConfigurationIPv6Auto

NetworkInterfaceAddressConfigurationState ¶

Configurable network address configuration of a network interface

Properties

ipv4

NetworkInterfaceAddressFamilyStateIPv4, optional

IPv4 Network address configuration

ipv4

address_configurations

Array of any of NetworkAddressConfigurationIPv4Static or NetworkAddressConfigurationIPv4DHCP, optional

NetworkAddressConfigurationIPv4Static[]

method string, one of [`static`, `dhcp`], required	Configuration method used for the address.
address NetworkInterfaceAddressIPv4 (string), required	IPv4 network address in CIDR notation
gateway NetworkAddressIPv4 (string), optional	default gateway for outgoing traffic

NetworkAddressConfigurationIPv4DHCP[]

method string, one of [`static`, `dhcp`], required	Configuration method used for the address.

ipv6

NetworkInterfaceAddressFamilyStateIPv6, optional

IPv6 Network address configuration

ipv6

address_configurations

Array of any of NetworkAddressConfigurationIPv6Static, NetworkAddressConfigurationIPv6DHCP or NetworkAddressConfigurationIPv6Auto, optional

NetworkAddressConfigurationIPv6Static[]

method string, one of [`static`, `dhcp`, `auto`], required	Configuration method used for the address.
address NetworkInterfaceAddressIPv6 (string), required	IPv6 network address in CIDR notation
gateway NetworkAddressIPv6 (string), optional	default gateway for outgoing traffic

NetworkAddressConfigurationIPv6DHCP[]

method string, one of [`static`, `dhcp`, `auto`], required	Configuration method used for the address.

NetworkAddressConfigurationIPv6Auto[]

method string, one of [`static`, `dhcp`, `auto`], required	Configuration method used for the address.

Remove all IPv6 address configurations

{
  "ipv6": {
    "address_configurations": []
  }
}

Replace existing IPv4 configuration with DHCP

{
  "ipv4": {
    "address_configurations": [
      {
        "method": "dhcp"
      }
    ]
  }
}

Set static and dynamic IPv4 configuration

{
  "ipv4": {
    "address_configurations": [
      {
        "method": "dhcp"
      },
      {
        "method": "static",
        "address": "192.168.0.100/24"
      }
    ]
  }
}

NetworkInterfaceAddressesIPv4 ¶

Properties

current_addresses

Array of WrappedNetworkInterfaceAddressIPv4, required

WrappedNetworkInterfaceAddressIPv4[]

address NetworkInterfaceAddressIPv4 (string), required	IPv4 network address in CIDR notation

NetworkInterfaceAddressesIPv6 ¶

Properties

current_addresses

Array of WrappedNetworkInterfaceAddressIPv6, required

WrappedNetworkInterfaceAddressIPv6[]

address NetworkInterfaceAddressIPv6 (string), required	IPv6 network address in CIDR notation

NetworkInterfaceAddressFamilyInformationIPv4 ¶

IPv4 Network address configuration

Properties

address_configurations

Array of any of NetworkAddressConfigurationIPv4Static or NetworkAddressConfigurationIPv4DHCP, optional

NetworkAddressConfigurationIPv4Static[]

method string, one of [`static`, `dhcp`], required	Configuration method used for the address.
address NetworkInterfaceAddressIPv4 (string), required	IPv4 network address in CIDR notation
gateway NetworkAddressIPv4 (string), optional	default gateway for outgoing traffic

NetworkAddressConfigurationIPv4DHCP[]

method string, one of [`static`, `dhcp`], required	Configuration method used for the address.

current_addresses

Array of WrappedNetworkInterfaceAddressIPv4, required

WrappedNetworkInterfaceAddressIPv4[]

address NetworkInterfaceAddressIPv4 (string), required	IPv4 network address in CIDR notation

Example

{
  "address_configurations": [
    {
      "method": "static",
      "address": "169.254.168.150/16"
    }
  ],
  "current_addresses": [
    {
      "address": "169.254.168.150/16"
    }
  ]
}

NetworkInterfaceAddressFamilyInformationIPv6 ¶

IPv6 Network address configuration

Properties

address_configurations

Array of any of NetworkAddressConfigurationIPv6Static, NetworkAddressConfigurationIPv6DHCP or NetworkAddressConfigurationIPv6Auto, optional

NetworkAddressConfigurationIPv6Static[]

method string, one of [`static`, `dhcp`, `auto`], required	Configuration method used for the address.
address NetworkInterfaceAddressIPv6 (string), required	IPv6 network address in CIDR notation
gateway NetworkAddressIPv6 (string), optional	default gateway for outgoing traffic

NetworkAddressConfigurationIPv6DHCP[]

method string, one of [`static`, `dhcp`, `auto`], required	Configuration method used for the address.

NetworkAddressConfigurationIPv6Auto[]

method string, one of [`static`, `dhcp`, `auto`], required	Configuration method used for the address.

current_addresses

Array of WrappedNetworkInterfaceAddressIPv6, required

WrappedNetworkInterfaceAddressIPv6[]

address NetworkInterfaceAddressIPv6 (string), required	IPv6 network address in CIDR notation

Example

{
  "address_configurations": [
    {
      "method": "static",
      "address": "fda0:576b:c643:100::100/64"
    },
    {
      "method": "auto"
    }
  ],
  "current_addresses": [
    {
      "address": "fda0:576b:c643:100::100/64"
    },
    {
      "address": "fd01::40f:10ff:fe02:e6f/64"
    },
    {
      "address": "fe80::40f:10ff:fe02:e6f/64"
    }
  ]
}

NetworkInterfaceAddressFamilyStateIPv4 ¶

IPv4 Network address configuration

Properties

address_configurations

Array of any of NetworkAddressConfigurationIPv4Static or NetworkAddressConfigurationIPv4DHCP, optional

NetworkAddressConfigurationIPv4Static[]

method string, one of [`static`, `dhcp`], required	Configuration method used for the address.
address NetworkInterfaceAddressIPv4 (string), required	IPv4 network address in CIDR notation
gateway NetworkAddressIPv4 (string), optional	default gateway for outgoing traffic

NetworkAddressConfigurationIPv4DHCP[]

method string, one of [`static`, `dhcp`], required	Configuration method used for the address.

NetworkInterfaceAddressFamilyStateIPv6 ¶

IPv6 Network address configuration

Properties

address_configurations

Array of any of NetworkAddressConfigurationIPv6Static, NetworkAddressConfigurationIPv6DHCP or NetworkAddressConfigurationIPv6Auto, optional

NetworkAddressConfigurationIPv6Static[]

method string, one of [`static`, `dhcp`, `auto`], required	Configuration method used for the address.
address NetworkInterfaceAddressIPv6 (string), required	IPv6 network address in CIDR notation
gateway NetworkAddressIPv6 (string), optional	default gateway for outgoing traffic

NetworkAddressConfigurationIPv6DHCP[]

method string, one of [`static`, `dhcp`, `auto`], required	Configuration method used for the address.

NetworkAddressConfigurationIPv6Auto[]

method string, one of [`static`, `dhcp`, `auto`], required	Configuration method used for the address.

NetworkInterfaceAddressIPv4 ¶

IPv4 network address in CIDR notation

Type Information

NetworkInterfaceAddressIPv4 (string)

Example
```
192.168.1.100/24
```

NetworkInterfaceAddressIPv6 ¶

IPv6 network address in CIDR notation

Type Information

NetworkInterfaceAddressIPv6 (string)

Example
```
fda0:576b:c643:100:40f:10ff:fe02:e6f/64
```

NetworkInterfaceInformation ¶

Description of the currently active addresses of the interface and its configuration.

Properties

iface

NetworkInterfaceName (string), pattern: ^[a-z0-9-]+$, required, read-only

unique name describing a network interface

hardware_address

MacAddress (string), pattern: ^([a-f0-9]{2}:){5}[a-f0-9]{2}$, required, read-only

unique hardware address of a network interface

has_link

boolean, required, read-only

current physical connection status (whether a cable is plugged in or not)

ipv4

NetworkInterfaceAddressFamilyStateIPv4, optional

IPv4 Network address configuration

ipv4

address_configurations

Array of any of NetworkAddressConfigurationIPv4Static or NetworkAddressConfigurationIPv4DHCP, optional

NetworkAddressConfigurationIPv4Static[]

method string, one of [`static`, `dhcp`], required	Configuration method used for the address.
address NetworkInterfaceAddressIPv4 (string), required	IPv4 network address in CIDR notation
gateway NetworkAddressIPv4 (string), optional	default gateway for outgoing traffic

NetworkAddressConfigurationIPv4DHCP[]

method string, one of [`static`, `dhcp`], required	Configuration method used for the address.

ipv6

NetworkInterfaceAddressFamilyStateIPv6, optional

IPv6 Network address configuration

ipv6

address_configurations

Array of any of NetworkAddressConfigurationIPv6Static, NetworkAddressConfigurationIPv6DHCP or NetworkAddressConfigurationIPv6Auto, optional

NetworkAddressConfigurationIPv6Static[]

method string, one of [`static`, `dhcp`, `auto`], required	Configuration method used for the address.
address NetworkInterfaceAddressIPv6 (string), required	IPv6 network address in CIDR notation
gateway NetworkAddressIPv6 (string), optional	default gateway for outgoing traffic

NetworkAddressConfigurationIPv6DHCP[]

method string, one of [`static`, `dhcp`, `auto`], required	Configuration method used for the address.

NetworkAddressConfigurationIPv6Auto[]

method string, one of [`static`, `dhcp`, `auto`], required	Configuration method used for the address.

Remove all IPv6 address configurations

{
  "ipv6": {
    "address_configurations": []
  }
}

Replace existing IPv4 configuration with DHCP

{
  "ipv4": {
    "address_configurations": [
      {
        "method": "dhcp"
      }
    ]
  }
}

Set static and dynamic IPv4 configuration

{
  "ipv4": {
    "address_configurations": [
      {
        "method": "dhcp"
      },
      {
        "method": "static",
        "address": "192.168.0.100/24"
      }
    ]
  }
}

NetworkInterfaceName ¶

unique name describing a network interface

Type Information

NetworkInterfaceName (string), pattern: ^[a-z0-9-]+$

Example
```
eth0
```

NetworkInterfaceStaticData ¶

Properties

iface NetworkInterfaceName (string), pattern: `^[a-z0-9-]+$`, required	unique name describing a network interface
hardware_address MacAddress (string), pattern: `^([a-f0-9]{2}:){5}[a-f0-9]{2}$`, required	unique hardware address of a network interface
has_link boolean, required	current physical connection status (whether a cable is plugged in or not)

NormalizationConstant ¶

Normalization constants are related to the White Reference.

Its content is subject to internal use. Thus it should not be accessed directly, but only through the related API endpoints (e.g. /api/sensor/detection-profiles/{itemId}/white-reference).

Type Information

Array of number

ReleaseChannel ¶

Describes the kind of a publication

Releases on the stable channel are generally considered well-tested and are recommended for use in production.

Releases on the feature add new features but haven’t been tested as much as a stable release. Feature releases can but should only be used in production with careful consideration.

Type Information

ReleaseChannel (string), one of [stable, feature] , default: stable

Example
```
stable
```

SampleRate ¶

Type Information

SampleRate (number), minimum: 0.01

SamplingSettings ¶

Sampling Settings describe all details of the sampling process.

Its attributes may be queried and inspected (e.g. in order to retrieve the current sample rate).

Most values stored within the Sampling Settings should not be modified directly. The related API endpoint /api/sensor/detection-profiles/current/autogain should be used instead.

Properties

led_intensity number, minimum: 0, maximum: 1, required	relative intensity of the internal emitter during the light phase
base_sample_rate SampleRate (number), minimum: 0.01, required	The base sample rate determines the duration of a sampling period. After each sampling period, the gathered data is processed and a new detection result is calculated (e.g. the most suitable Matcher for the given sample). This may affect the state of the Switching Outputs or trigger configured actions. Thus the base sample rate defines the maximum rate of changes for the Switching Outputs. See also the effective sample rate.
effective_sample_rate SampleRate (number), minimum: 0.01, required	The effective sample rate is the numeric product of the base sample rate and the number of averages. It determines the minimum duration that a target needs to be sampled in order to determine its visual appearance correctly. With the default value of average set to one, this value is equal to the base sample rate.
minimum_wanted_sample_rate SampleRate (number), minimum: 0.01, required	This informational value represents the sample rate that was requested during the most recent Autogain operation. The effective sample rate may deviate from the wanted sample rate, if the requested sample rate was not achievable due to limitations of the sensor (e.g. exceeding the supported sample rate) or due to the environment (e.g. not enough light, thus a slower amplification with higher gain was necessary).
sample_light_phase boolean, required	defines if the sensor should periodically activate the internal emitter for sampling
sample_dark_phase boolean, required	defines if the sensor should periodically deactivate the internal emitter for sampling
averages AverageSampleCount (integer), minimum: 1, required	Number of previous samples to be averaged for every sampling result. A rolling averaging algorithm is applied to the samples.
suppress_intermediate_averages SuppressIntermediateAverages (boolean), required	If set to True, then only one sample is emitted after the configured number of averages is processed. Otherwise all intermdiate results are emitted, too. This toggles the behaviour between moving averaging and block-based averaging. Switching outputs are updated less frequently, if intermediate averages are suppressed.
amplification AmplificationLevel (integer), required	The amplification level specifies the internal configuration of an amplifier. This value is not meant to be manipulated by regular users. It should be handled as is (stored, transmitted and applied without modification or introspection).

Example

{
  "led_intensity": 0.7,
  "base_sample_rate": 1000,
  "effective_sample_rate": 1000,
  "minimum_wanted_sample_rate": 1000,
  "sample_light_phase": true,
  "sample_dark_phase": true,
  "averages": 1,
  "amplification": 5,
  "suppress_intermediate_averages": false
}

SensorCapabilities ¶

Provide access to the sensoric details supported by this device (e.g. colorspaces, input and output lines, ...).

Properties

maximum_sample_rate

integer, required

the maximum sample rate the sensor supports

tolerances

Array of ColorTolerance (union), required

List of tolerance specifications supported by the sensor

InfiniteColorTolerance[]

limits object, required	limits
shape ToleranceShapeName (string), required	Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via `/api/sensor/capabilities`.

SphereColorTolerance[]

limits

object, required

limits

radius number, required

shape

ToleranceShapeName (string), required

Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via /api/sensor/capabilities.

CylinderColorTolerance[]

limits

object, required

limits

radius number, required
half_height number, required

shape

ToleranceShapeName (string), required

Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via /api/sensor/capabilities.

BoxColorTolerance[]

limits

object, required

limits

half_edges Array of number, minimum items: 3, maximum items: 3, required

shape

ToleranceShapeName (string), required

Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via /api/sensor/capabilities.

output_drivers

Array of SwitchingOutputDriver (string), required

List of supported electrical output drivers

trigger_sources

Array of TriggerSource, required

Contains the list of available trigger source with their corresponding trigger events. Trigger events can be automated to execute certain actions.

TriggerSource[]

name

string, required

Name of the trigger input

events

Array of TriggerEvent, required

TriggerEvent[]

name TriggerEventName (string), required

output_pin_count

integer, required

Number of available switching output lines

actions

Array of Action, required, Deprecated

Deprecated: use /api/actions instead

Action[]

name string, required	Unique name of the action
arguments object, required	arguments

colorspaces

Array of Colorspace, required

List of supported colorspaces.

Colorspace[]

name

string, required

space_id

ColorspaceID, required

Unique name of a colorspace

axes

Array of ColorspaceAxis, minimum items: 3, maximum items: 3, required

ColorspaceAxis[]

id string, required	Unique name
label string, required	Human-readable name
minimum number, required	lowest expected value of a color along this axis under usual circumstances
maximum number, required	highest expected value of a color along this axis under usual circumstances

colorspace_tolerance_maps

Array of ColorspaceToleranceMap, required

The hue-related attributes (e.g. "a" and "b" for the "Lab*" colorspace) are used for the "radius" of a cylinder tolerance shape and the second and third edges of the box tolerance shape.

The colorspace_tolerance_maps define these relationships between colorspaces and tolerances.

ColorspaceToleranceMap[]

colorspace_id

ColorspaceID (string), required

Unique name of a colorspace

tolerance_shape

ToleranceShapeName (string), required

Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via /api/sensor/capabilities.

limits_axes_map

object, required

limits_axes_map

half_height Array of string, optional
half_edges Array of string, optional
radius Array of string, optional

settings_categories

Array of string, required

List of categories that can be selected during import to control which settings should be applied. See the documentation for the POST request to `/api/seetings.

maximum_detectables_count

integer, required

Maximum number of color positions (Detectable) to be stored in a detection profile.

maximum_matchers_count

integer, required

Maximum number of detection results (Matcher) be stored in a detection profile.

features

Array of string, required

List of specific sensor feature flags describing the supported operations of this sensor.

Example

{
  "output_pin_count": 8,
  "tolerances": [
    {
      "shape": "infinite",
      "limits": {}
    },
    {
      "shape": "sphere",
      "limits": {
        "radius": 2
      }
    },
    {
      "shape": "cylinder",
      "limits": {
        "half_height": 4,
        "radius": 2
      }
    },
    {
      "shape": "box",
      "limits": {
        "half_edges": [
          4,
          2,
          2
        ]
      }
    }
  ],
  "actions": [
    {
      "name": "enable_switching_output",
      "arguments": {}
    },
    {
      "name": "teach_single",
      "arguments": {}
    }
  ],
  "maximum_sample_rate": 20000,
  "maximum_detectables_count": 256,
  "maximum_matchers_count": 256,
  "trigger_sources": [
    {
      "name": "trigger_0",
      "events": [
        {
          "name": "trigger_0_level_high"
        },
        {
          "name": "trigger_0_level_low"
        },
        {
          "name": "trigger_0_edge_rising"
        },
        {
          "name": "trigger_0_edge_falling"
        }
      ]
    },
    {
      "name": "trigger_1",
      "events": [
        {
          "name": "trigger_1_level_high"
        },
        {
          "name": "trigger_1_level_low"
        },
        {
          "name": "trigger_1_edge_rising"
        },
        {
          "name": "trigger_1_edge_falling"
        }
      ]
    },
    {
      "name": "trigger_2",
      "events": [
        {
          "name": "trigger_2_level_high"
        },
        {
          "name": "trigger_2_level_low"
        },
        {
          "name": "trigger_2_edge_rising"
        },
        {
          "name": "trigger_2_edge_falling"
        }
      ]
    },
    {
      "name": "trigger_3",
      "events": [
        {
          "name": "trigger_3_level_high"
        },
        {
          "name": "trigger_3_level_low"
        },
        {
          "name": "trigger_3_edge_rising"
        },
        {
          "name": "trigger_3_edge_falling"
        }
      ]
    }
  ],
  "colorspaces": [
    {
      "axes": [
        {
          "id": "L",
          "label": "L*",
          "minimum": 0,
          "maximum": 100
        },
        {
          "id": "a",
          "label": "a*",
          "minimum": -500,
          "maximum": 500
        },
        {
          "id": "b",
          "label": "b*",
          "minimum": -200,
          "maximum": 200
        }
      ],
      "name": "L*a*b*",
      "space_id": "Lab"
    },
    {
      "axes": [
        {
          "id": "L",
          "label": "L*",
          "minimum": 0,
          "maximum": 100
        },
        {
          "id": "u",
          "label": "u*",
          "minimum": 0,
          "maximum": 100
        },
        {
          "id": "v",
          "label": "v*",
          "minimum": 0,
          "maximum": 100
        }
      ],
      "name": "L*u*v*",
      "space_id": "Luv"
    },
    {
      "axes": [
        {
          "id": "X",
          "label": "X",
          "minimum": 0,
          "maximum": 120
        },
        {
          "id": "Y",
          "label": "Y",
          "minimum": 0,
          "maximum": 100
        },
        {
          "id": "Z",
          "label": "Z",
          "minimum": 0,
          "maximum": 120
        }
      ],
      "name": "XYZ",
      "space_id": "XYZ"
    },
    {
      "axes": [
        {
          "id": "x",
          "label": "x",
          "minimum": 0,
          "maximum": 1
        },
        {
          "id": "y",
          "label": "y",
          "minimum": 0,
          "maximum": 1
        },
        {
          "id": "Y",
          "label": "Y",
          "minimum": 0,
          "maximum": 100
        }
      ],
      "name": "xyY",
      "space_id": "xyY"
    },
    {
      "axes": [
        {
          "id": "L",
          "label": "L*",
          "minimum": 0,
          "maximum": 100
        },
        {
          "id": "u",
          "label": "u'",
          "minimum": 0,
          "maximum": 1
        },
        {
          "id": "v",
          "label": "v'",
          "minimum": 0,
          "maximum": 1
        }
      ],
      "name": "L*u'v'",
      "space_id": "uvL"
    }
  ],
  "output_drivers": [
    "off",
    "npn",
    "pnp",
    "push-pull"
  ],
  "colorspace_tolerance_maps": [
    {"colorspace_id": "Lab", "tolerance_shape": "box",
     "limits_axes_map": {"half_edges": ["L", "a", "b"]}},
    {"colorspace_id": "Lab", "tolerance_shape": "cylinder",
     "limits_axes_map": {"half_height": ["L"], "radius": ["a", "b"]}},
    {"colorspace_id": "Luv", "tolerance_shape": "box",
     "limits_axes_map": {"half_edges": ["L", "u", "v"]}},
    {"colorspace_id": "Luv", "tolerance_shape": "box",
     "limits_axes_map": {"half_height": ["L"], "radius": ["u", "v"]}}
  ],
  "features": [
      "eliza",
      "modbus"
  ],
  "settings_categories": [
    "access",
    "defaults",
    "firmware",
    "keypad",
    "network",
    "outputs",
    "peripherals",
    "sensor",
    "system"
  ]
}

SerialDisabledSettings ¶

Properties

type string, one of [`eliza`, `modbus`, `nil`] , default: `eliza`, required

SerialElizaSettings ¶

Properties

type string, one of [`eliza`, `modbus`, `nil`] , default: `eliza`, required

SerialModbusSettings ¶

Properties

type string, one of [`eliza`, `modbus`, `nil`] , default: `eliza`, required
slave_id any of number or null, required
frame_format string, one of [`rtu`, `ascii`] , default: `rtu`, required

SignalColor ¶

A custom color name. How and what color will be displayed is defined by the client.

Type Information

any of string or null

SphereColorTolerance ¶

Properties

limits

object, required

limits

radius number, required

shape

ToleranceShapeName (string), required

Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via /api/sensor/capabilities.

SupportedTimezones ¶

List of timezones supported by the device

Type Information

Array of string

Example

[
  "Africa/Casablanca",
  "Antarctica/Troll",
  "Europe/Berlin",
  "UTC"
]

SuppressIntermediateAverages ¶

If set to True, then only one sample is emitted after the configured number of averages is processed. Otherwise all intermdiate results are emitted, too. This toggles the behaviour between moving averaging and block-based averaging. Switching outputs are updated less frequently, if intermediate averages are suppressed.

Type Information

SuppressIntermediateAverages (boolean)

SwitchingOutputDriver ¶

The Output Driver defines the electrical behaviour of the switching outputs. The supported output drivers can be retrieved via /api/sensor/capabilities.

Type Information

SwitchingOutputDriver (string)

Example
```
push-pull
```

SwitchingOutputs ¶

Eletrical output lines can drive external actors in different electrical modes.

Properties

output_driver SwitchingOutputDriver (string), required	The Output Driver defines the electrical behaviour of the switching outputs. The supported output drivers can be retrieved via `/api/sensor/capabilities`.
count integer, required	Number of available output lines

Example

{
  "count": 8,
  "output_driver": "push-pull"
}

SwitchingOutputsWritable ¶

Eletrical output lines can drive external actors in different electrical modes.

Properties

output_driver SwitchingOutputDriver (string), required	The Output Driver defines the electrical behaviour of the switching outputs. The supported output drivers can be retrieved via `/api/sensor/capabilities`.

SystemSettings ¶

Properties

hostname Hostname, pattern: `^(?:[a-zA-Z0-9](?:[a-zA-Z0-9\-][a-zA-Z0-9])?\.)[a-zA-Z0-9](?:[a-zA-Z0-9\-]*[a-zA-Z0-9])?$`, optional	Human-readable name identifying the device in the network
uptime any of number or null, optional, read-only	The current system uptime in seconds. Though highly unlikely can be nil in case the system reported an invalid value.

Example

{
  "hostname": "blickwerk-7454232361"
}

SystemTimeSettings ¶

Properties

now Timestamp (string), optional	current time from the perspective of the sensor
timezone string, optional	currently configured timezone
ntp_servers Array of string, optional	one or more network time servers
default_ntp_servers Array of string, optional, read-only	preconfigured network time servers

Example

{
  "now": "2018-01-24T15:45:15.694004+01:00",
  "timezone": "Europe/Berlin",
  "ntp_servers": [
    "pool.ntp.org"
  ],
  "default_ntp_servers": [
    "pool.ntp.org"
  ]
}

Timestamp ¶

Timestamp (Format: ISO 8601)

Type Information

Timestamp (string)

Example
```
2018-01-24T14:04:26+01:00
```

TimestampBackendUptime ¶

The timestamp (given in microseconds) is based on the uptime of the internal analog sensor backend. It may get reset to zero under specific conditions.

Type Information

TimestampBackendUptime (number), minimum: 0

ToleranceShapeName ¶

Name of the geometrical shape of the tolerance. The supported tolerance shapes can be retrieved via /api/sensor/capabilities.

Type Information

ToleranceShapeName (string)

TransformedColor ¶

A color represented by a coordinate in the colorspace. The array indices of the values property match the order of the colorspace.axes property of currently used detection profile.

Properties

values Array of number, minimum items: 3, maximum items: 3, required	Location in a colorspace

TriggerEvent ¶

Trigger Events can be emitted by their trigger source. Actions can be attached to a Trigger Event (see /api/sensor/action-triggers).

Properties

name TriggerEventName (string), required

TriggerEventName ¶

Type Information

TriggerEventName (string)

Example
```
trigger_0_level_high
```

TriggerSource ¶

Each Trigger Source is a peripheral input with the ability to emit one or more Trigger Events.

Properties

name

string, required

Name of the trigger input

events

Array of TriggerEvent, required

TriggerEvent[]

name TriggerEventName (string), required

Example

{
  "name": "trigger_0",
  "events": [
    {
      "name": "trigger_0_level_high"
    },
    {
      "name": "trigger_0_level_low"
    },
    {
      "name": "trigger_0_edge_rising"
    },
    {
      "name": "trigger_0_edge_falling"
    }
  ]
}

TriggerSourcesStatus ¶

The sensor has a number of input lines that can be used as trigger sources. The event counters are updated periodically (approximately every second).

Properties

trigger_sources

Array of object, required

object[]

name

string, required

event_counters

object, required

event_counters

edge_falling number, required
edge_rising number, required
level_low number, required
level_high number, required

Example

{
  "trigger_sources": [
    {
      "name": "trigger_0",
      "event_counters": {
        "edge_falling": 22,
        "edge_rising": 23,
        "level_low": 35124823,
        "level_high": 15
      }
    },
    {
      "name": "trigger_1",
      "event_counters": {
        "edge_falling": 0,
        "edge_rising": 0,
        "level_low": 35124832,
        "level_high": 0
      }
    }
  ]
}

User ¶

Properties

name string, pattern: `^[\w-]+$`, required, read-only	unique name identifying an account
password string, optional	Password assigned to this account (only writable; never returned in responses). Either a `password` or a `password_hash` needs to be supplied when creating a new user or changing a password.
password_hash HashDigest (string), pattern: `^[a-f0-9]+$`, optional	Password hash assigned to this account. Either a `password` or a `password_hash` needs to be supplied when creating a new user or changing a password.
roles Array of string, optional	The roles assigned to an account define its set of permissions.

Example
```
{
  "name": "alice"
}
```

UUID ¶

unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8

Type Information

UUID (string), pattern: ^[a-f0-9-]+$

Example
```
a014e415-0fec-4734-ac3f-30da0a5f3899
```

WantedSwitchingOutputsState ¶

The combination of tristate values describes a logical state of the switching outputs of the sensor.

The states true or false cause the output to go up or down. The state null keeps the previous state of the output unchanged.

Properties

uuid UUID (string), pattern: `^[a-f0-9-]+$`, required	unique identifier (UUID) as defined by RFC 4122, ITU-T Rec. X.667, and ISO/IEC 9834-8
states Array of any of boolean or null, required	List of True/False/Null values describing the wanted states of the Switching Outputs

Example

{
  "uuid": "3f26aff4-8650-42a0-b319-51776c443fbc",
  "states": [
    true,
    false,
    false,
    false,
    false,
    false,
    false,
    false
  ]
}

WhiteReference ¶

The White Reference attribute is used for indicating a custom color balancing.

Its content is subject to internal use. Thus it should not be accessed directly, but only through the related API endpoints (e.g. /api/sensor/detection-profiles/{itemId}/white-reference).

Type Information

Array of number

WrappedNetworkInterfaceAddressIPv4 ¶

network addresses (IPv4) in CIDR notation

Properties

address NetworkInterfaceAddressIPv4 (string), required	IPv4 network address in CIDR notation

WrappedNetworkInterfaceAddressIPv6 ¶

network addresses (IPv6) in CIDR notation

Properties

address NetworkInterfaceAddressIPv6 (string), required	IPv6 network address in CIDR notation