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

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.

  1. Clear all settings:

    $ curl -X DELETE http://sensor/api/settings
    
    > Invoke-RestMethod -Method DELETE -Uri http://<sensorIP>/api/settings
    
  2. Place a neutral white color target in front of your sensor's optics.

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

    $ curl -X POST http://<sensorIP>/api/detection-profiles/current/autogain
    
    > Invoke-RestMethod -Method POST -Uri http://<sensorIP>/api/sensor/detection-profiles/current/autogain
    
  4. Place your wanted target object in front of the sensor's optics.

  5. Teach this color:

    $ curl -X POST http://<sensorIP>/api/sensor/detectables
    
    > Invoke-RestMethod -Method POST -Uri http://<sensorIP>/api/sensor/detectables
    
  6. 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.
  7. 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

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.

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
Properties (object)
data
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 indentifying the organization distributing this device

vendor_name
DeviceVendorName, required

Name of vendor of this device

device_id
DeviceSerialNumber, optional, Deprecated

Deprecated

model
string, optional, Deprecated

Deprecated

vendor
DeviceVendorName, optional, Deprecated

Deprecated

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 [01] , 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 [jsoncsv] , 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
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

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

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

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

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

List of non-negative distances according to the tolerance shape of the selected matcher.

The order of values corresponds to the order of limits of the tolerance shape.

The number of fields in the array may be greater than the number of limits values. Subsequent fields contain null and may be ignored.

output_pattern

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
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

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

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

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

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

List of non-negative distances according to the tolerance shape of the selected matcher.

The order of values corresponds to the order of limits of the tolerance shape.

The number of fields in the array may be greater than the number of limits values. Subsequent fields contain null and may be ignored.

output_pattern

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 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
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

name
string, required

human-readable name of the matcher

tolerance

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

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), 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
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

name
string, required

human-readable name of the matcher

tolerance

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

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), 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.

Examples
  • Example
    {
      "uuid": "9ffaa31f-8011-44f5-bb2a-f91e4be50764",
      "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
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

name
string, required

human-readable name of the matcher

tolerance

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

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), 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
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
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

name
string, required

human-readable name of the matcher

tolerance

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

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), 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
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

name
string, required

human-readable name of the matcher

tolerance

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

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), 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.

Examples
  • Example
    {
      "uuid": "9ffaa31f-8011-44f5-bb2a-f91e4be50764",
      "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
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

name
string, required

human-readable name of the matcher

tolerance

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

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), 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
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
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
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

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

reference to the Matcher containing this Detectable

color

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.

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 ColorDetectables matching the filter.

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
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

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

reference to the Matcher containing this Detectable

color

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.

Examples
  • Example
    {
      "uuid": "9f968e8a-ad9c-45ce-9beb-a55011856a99",
      "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
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

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

reference to the Matcher containing this Detectable

color

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
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
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

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

reference to the Matcher containing this Detectable

color

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.

Examples
  • Example
    {
      "uuid": "9f968e8a-ad9c-45ce-9beb-a55011856a99",
      "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
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

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

reference to the Matcher containing this Detectable

color

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
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
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
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

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

reference to the Matcher containing this Detectable

color

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
Examples
  • Example
    a014e415-0fec-4734-ac3f-30da0a5f3899
Response
Body
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
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

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

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
number, minimum: 0, 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

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

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 attribute within the Sampling Settings is the averages value. It is safe to change it, even though the default values 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.

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).

Examples
  • Example
    {
      "name": "#0",
      "uuid": "2475df8d-85f0-4208-ba60-dce6cb282a96",
      "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,
        "base_sample_rate": 1000,
        "sample_dark_phase": true,
        "effective_sample_rate": 1000
      }
    }
    
Response
Body
Properties (object)
data

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

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

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
number, minimum: 0, 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

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

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 attribute within the Sampling Settings is the averages value. It is safe to change it, even though the default values 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.

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
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.

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 DetectionProfiles matching the filter.

Response
Body
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

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.

The empty response indicates success

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

Retrieves a list of available DetectionProfiles

Response
Body
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

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

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
number, minimum: 0, 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

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

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 attribute within the Sampling Settings is the averages value. It is safe to change it, even though the default values 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.

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

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

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
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

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

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
number, minimum: 0, 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

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

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 attribute within the Sampling Settings is the averages value. It is safe to change it, even though the default values 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.

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).

Examples
  • Example
    {
      "name": "#0",
      "uuid": "2475df8d-85f0-4208-ba60-dce6cb282a96",
      "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,
        "base_sample_rate": 1000,
        "sample_dark_phase": true,
        "effective_sample_rate": 1000
      }
    }
    
Response
Body
Properties (object)
data

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

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

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
number, minimum: 0, 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

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

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 attribute within the Sampling Settings is the averages value. It is safe to change it, even though the default values 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.

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
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
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
Properties (object)
data

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

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

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
number, minimum: 0, 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

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

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 attribute within the Sampling Settings is the averages value. It is safe to change it, even though the default values 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.

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
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.

Examples
  • Example
    {
      "level": 0.7,
      "minimum_sample_rate": 1500,
      "enable_internal_emitter": true,
      "enable_ambient_light_compensation": true
    }
Response
Body
Properties (object)
data
object, required
data
sampling_settings

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 attribute within the Sampling Settings is the averages value. It is safe to change it, even though the default values calculated during an autogain operation should be optimal for most detection tasks.

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.

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

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).

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
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
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
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
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
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

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).

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
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.

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 ActionTriggers matching the filter.

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
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
Examples
  • Example
    {
      "uuid": "3f26aff4-8650-42a0-b319-51776c443fbc",
      "event": "trigger_0_edge_falling",
      "actions": [
        {
          "name": "enable_switching_output",
          "arguments": {}
        }
      ]
    }
Response
Body
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
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
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
Examples
  • Example
    {
      "uuid": "3f26aff4-8650-42a0-b319-51776c443fbc",
      "event": "trigger_0_edge_falling",
      "actions": [
        {
          "name": "enable_switching_output",
          "arguments": {}
        }
      ]
    }
Response
Body
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
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
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
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
Properties (object)
data

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.

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
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
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.

Upload Settings
POST /settings

Replaces the sensors current 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.

Request
Body
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

Input validation failed

Body
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

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.

Request
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

Input validation failed

Body
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

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
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

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
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

Examples
  • Example
    {
      "hostname": "blickwerk-7454232361"
    }
    
Response
Body
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

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
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
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

Resets the sensors firmware to its factory default and initiates a reboot. After completion the sensor will use its original firmware and all settings are reset to their defaults.

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
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
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
Properties (object)
data
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
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

Examples
  • 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
Properties (object)
data
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
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
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
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
Properties (object)
data
NetworkInterfaceAddressConfigurationState[]
ipv4

IPv4 Network address configuration

ipv4
address_configurations
NetworkAddressConfigurationIPv4Static[]
method
string, one of [staticdhcp], 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 [staticdhcp], required

Configuration method used for the address.

ipv6

IPv6 Network address configuration

ipv6
address_configurations
NetworkAddressConfigurationIPv6Static[]
method
string, one of [staticdhcpauto], 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 [staticdhcpauto], required

Configuration method used for the address.

NetworkAddressConfigurationIPv6Auto[]
method
string, one of [staticdhcpauto], 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
Properties (object)
data

Configurable network address configuration of a network interface

NetworkInterfaceAddressConfigurationState
ipv4

IPv4 Network address configuration

ipv4
address_configurations
NetworkAddressConfigurationIPv4Static[]
method
string, one of [staticdhcp], 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 [staticdhcp], required

Configuration method used for the address.

ipv6

IPv6 Network address configuration

ipv6
address_configurations
NetworkAddressConfigurationIPv6Static[]
method
string, one of [staticdhcpauto], 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 [staticdhcpauto], required

Configuration method used for the address.

NetworkAddressConfigurationIPv6Auto[]
method
string, one of [staticdhcpauto], 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
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

IPv4 Network address configuration

ipv4
address_configurations
NetworkAddressConfigurationIPv4Static[]
method
string, one of [staticdhcp], 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 [staticdhcp], required

Configuration method used for the address.

ipv6

IPv6 Network address configuration

ipv6
address_configurations
NetworkAddressConfigurationIPv6Static[]
method
string, one of [staticdhcpauto], 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 [staticdhcpauto], required

Configuration method used for the address.

NetworkAddressConfigurationIPv6Auto[]
method
string, one of [staticdhcpauto], required

Configuration method used for the address.

Examples
  • 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
Properties (object)
data

Configurable network address configuration of a network interface

NetworkInterfaceAddressConfigurationState
ipv4

IPv4 Network address configuration

ipv4
address_configurations
NetworkAddressConfigurationIPv4Static[]
method
string, one of [staticdhcp], 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 [staticdhcp], required

Configuration method used for the address.

ipv6

IPv6 Network address configuration

ipv6
address_configurations
NetworkAddressConfigurationIPv6Static[]
method
string, one of [staticdhcpauto], 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 [staticdhcpauto], required

Configuration method used for the address.

NetworkAddressConfigurationIPv6Auto[]
method
string, one of [staticdhcpauto], 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
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
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
Properties (object)
data

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.

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
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.

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.

Examples
  • Example
    {
      "locked": true,
      "visualization_url": "/media/keypad-image.svg"
    }
Response
Body
Properties (object)
data

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.

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
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
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
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
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
Properties (object)
data

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
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
Properties (object)
data

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
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 trigger source event statistics
GET /peripherals/trigger-sources Permission Scope peripherals

Response
Body
Properties (object)
data

The sensor has a number of input lines that can be used as trigger sources.

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

Actions

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.

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): the UUID of a matcher or null. In case of null the new detectable is assigned to a new matcher that is created whenever the action is executed. 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.
  • remove_matcher_detectables_before (optional): the boolean value specifies whether the original 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 "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

Retrieve Actions
GET /actions

Retrieves a list of available Actions

Response
Body
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
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
Properties (AnyAction (union))
ActionEnableSwitchingOutput

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

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 is undefined, the first matcher (i.e. the one with the output bitmask 0x01) is used.

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

ActionRunAutogain

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

Remove all stored Detectables belonging to any Matcher.

ActionRemoveAllDetectables
name
string, required

Unique name of the action

arguments
object, required
arguments
ActionRemoveAllMatchers

Remove all stored Matchers (including the related detectables).

ActionRemoveAllMatchers
name
string, required

Unique name of the action

arguments
object, required
arguments
Response
Body
Properties (object)
data
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

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

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

List of non-negative distances according to the tolerance shape of the selected matcher.

The order of values corresponds to the order of limits of the tolerance shape.

The number of fields in the array may be greater than the number of limits values. Subsequent fields contain null and may be ignored.

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

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

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.

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
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
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

Examples
  • tolerance
    {
      "uuid": "a7bd36b3-e9c1-4f60-8d7e-cf47634a28b1",
      "object_type": "matcher",
      "key": "tolerance",
      "value": {
        "shape": "sphere",
        "limits": {
          "radius": 4
        }
      }
    }
  • hold_time
    {
      "uuid": "55b35901-1ea6-4b3d-864a-60af15a9b0c5",
      "object_type": "matcher",
      "key": "hold_time",
      "value": 0
    }
  • reset_output_after_hold_time_expired
    {
      "uuid": "9ba8a7a4-7fa5-4bfc-8883-98d7b6084e91",
      "object_type": "matcher",
      "key": "reset_output_after_hold_time_expired",
      "value": false
    }
  • autogain_averages
    {
      "uuid": "eeb46031-10e5-4f13-901a-c7eb16aa0cf9",
      "object_type": "autogain",
      "key": "averages",
      "value": 0
    }
Response
Body
Properties (object)
data
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
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.

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 DefaultsMapValues matching the filter.

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
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

Examples
  • tolerance
    {
      "uuid": "a7bd36b3-e9c1-4f60-8d7e-cf47634a28b1",
      "object_type": "matcher",
      "key": "tolerance",
      "value": {
        "shape": "sphere",
        "limits": {
          "radius": 4
        }
      }
    }
  • hold_time
    {
      "uuid": "55b35901-1ea6-4b3d-864a-60af15a9b0c5",
      "object_type": "matcher",
      "key": "hold_time",
      "value": 0
    }
  • reset_output_after_hold_time_expired
    {
      "uuid": "9ba8a7a4-7fa5-4bfc-8883-98d7b6084e91",
      "object_type": "matcher",
      "key": "reset_output_after_hold_time_expired",
      "value": false
    }
  • autogain_averages
    {
      "uuid": "eeb46031-10e5-4f13-901a-c7eb16aa0cf9",
      "object_type": "autogain",
      "key": "averages",
      "value": 0
    }
Response
Body
Properties (object)
data
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
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
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
Properties (object)
data
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
Properties (object)
data

Information describing a firmware version.

FirmwareInformation
id
FirmwareBuildId (string), pattern: ^[a-f0-9]+$, required

unique ID for of this particular firmware image

channel
ReleaseChannel (string), one of [stablefeature] , 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
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 for of this particular firmware image

status
string, one of [incompletecompleteinvalid_signatureprocessing_failuremalformed_contentdevice_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
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 [01] , 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 for of this particular firmware image

expected_size
FirmwareImageSize (integer), minimum: 1, maximum: 1073741824, required

size of the firmware image in bytes

Response
Body
Properties (object)
data

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 for of this particular firmware image

status
string, one of [incompletecompleteinvalid_signatureprocessing_failuremalformed_contentdevice_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
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
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
Properties (object)
data

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 for of this particular firmware image

status
string, one of [incompletecompleteinvalid_signatureprocessing_failuremalformed_contentdevice_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
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
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
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 chunck (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
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
Properties (object)
data

Information describing a firmware version.

FirmwareInformation
id
FirmwareBuildId (string), pattern: ^[a-f0-9]+$, required

unique ID for of this particular firmware image

channel
ReleaseChannel (string), one of [stablefeature] , 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
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
Properties (object)
data

Settings related to the device's firmware and upgrades.

FirmwareSettings
release_channel
ReleaseChannel (string), one of [stablefeature] , 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
Properties (FirmwareSettings)
release_channel
ReleaseChannel (string), one of [stablefeature] , 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.

Examples
  • Example
    {
      "release_channel": "stable"
    }
Response
Body
Properties (object)
data

Settings related to the device's firmware and upgrades.

FirmwareSettings
release_channel
ReleaseChannel (string), one of [stablefeature] , 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
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
Properties (object)
data

Information describing the currently running firmware.

FirmwareRunningInformation
build_id
FirmwareBuildId (string), pattern: ^[a-f0-9]+$, required

unique ID for of this particular 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)?
  • 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 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
Properties (object)
data
AccessControlFeatures
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
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
Properties (object)
data

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
Properties (object)
data

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

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
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.

Examples
  • Example
    {
      "name": "alice"
    }
Response
Body
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
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.

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 Users matching the filter.

Response

The empty response indicates success

Retrieve Users
GET /access/users Permission Scope access

Retrieves a list of available Users

Response
Body
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
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.

Examples
  • Example
    {
      "name": "alice"
    }
Response
Body
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
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
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
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
Properties (object)
data
object, required
data
roles
Array of AccessRole, required
AccessRole[]
id
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)

Examples

  • Example
    view

AccessControlFeatures

Properties

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.

Examples

  • Example
    {
      "actions": [
        "view",
        "edit"
      ],
      "scopes": [
        "access",
        "miscellaneous",
        "network",
        "notify",
        "peripherals",
        "sensor",
        "settings",
        "system"
      ]
    }

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

id
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)

Examples

  • 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

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

Examples

  • 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

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

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

List of non-negative distances according to the tolerance shape of the selected matcher.

The order of values corresponds to the order of limits of the tolerance shape.

The number of fields in the array may be greater than the number of limits values. Subsequent fields contain null and may be ignored.

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

Examples

  • 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.

Examples

  • Example
    {
      "locked": true
    }

ActionResultRemoveAllDetectables

The response is empty and returns HTTP status 204.

Type Information

ActionResultRemoveAllMatchers

The response is empty and returns HTTP status 204.

Type Information

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.

Examples

  • 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

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.

Examples

  • Example
    {
      "uuid": "9f968e8a-ad9c-45ce-9beb-a55011856a99",
      "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

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 is undefined, the first matcher (i.e. the one with the output bitmask 0x01) is used.

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

Examples

  • 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

Examples

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

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

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.

Examples

  • 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

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

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

reference to the Matcher containing this Detectable

color

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.

Examples

  • Example
    {
      "uuid": "9f968e8a-ad9c-45ce-9beb-a55011856a99",
      "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).

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 (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

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

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

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

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

List of non-negative distances according to the tolerance shape of the selected matcher.

The order of values corresponds to the order of limits of the tolerance shape.

The number of fields in the array may be greater than the number of limits values. Subsequent fields contain null and may be ignored.

output_pattern

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

Examples

  • 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

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

name
string, required

human-readable name of the matcher

tolerance

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

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), 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.

Examples

  • Example
    {
      "uuid": "9ffaa31f-8011-44f5-bb2a-f91e4be50764",
      "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

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.

Properties

matcher
any of UUID (string) or null, optional

Deprecated

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

List of non-negative distances according to the tolerance shape of the selected matcher.

The order of values corresponds to the order of limits of the tolerance shape.

The number of fields in the array may be greater than the number of limits values. Subsequent fields contain null and may be ignored.

output_pattern

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

Examples

  • 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.

Examples

  • 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

Examples

  • 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

Examples

  • 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

Examples

  • 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.

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).

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

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.

Type Information

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

Examples

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

CurrentSwitchingOutputsState

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.

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

Examples

  • tolerance
    {
      "uuid": "a7bd36b3-e9c1-4f60-8d7e-cf47634a28b1",
      "object_type": "matcher",
      "key": "tolerance",
      "value": {
        "shape": "sphere",
        "limits": {
          "radius": 4
        }
      }
    }
  • hold_time
    {
      "uuid": "55b35901-1ea6-4b3d-864a-60af15a9b0c5",
      "object_type": "matcher",
      "key": "hold_time",
      "value": 0
    }
  • reset_output_after_hold_time_expired
    {
      "uuid": "9ba8a7a4-7fa5-4bfc-8883-98d7b6084e91",
      "object_type": "matcher",
      "key": "reset_output_after_hold_time_expired",
      "value": false
    }
  • autogain_averages
    {
      "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.

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.

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

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

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
number, minimum: 0, 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

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

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 attribute within the Sampling Settings is the averages value. It is safe to change it, even though the default values 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.

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).

Examples

  • Example
    {
      "name": "#0",
      "uuid": "2475df8d-85f0-4208-ba60-dce6cb282a96",
      "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,
        "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 indentifying the organization distributing this device

vendor_name
DeviceVendorName, required

Name of vendor of this device

device_id
DeviceSerialNumber, optional, Deprecated

Deprecated

model
string, optional, Deprecated

Deprecated

vendor
DeviceVendorName, optional, Deprecated

Deprecated

Examples

  • 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

DeviceVendorKey

Unique key indentifying the organization distributing this device

Type Information

Examples

  • Example
    acme

DeviceVendorName

Name of vendor of this device

Type Information

Examples

  • 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 for of this particular firmware image

Type Information

FirmwareBuildId (string), pattern: ^[a-f0-9]+$

Examples

  • Example
    d985c28e03a4eb39132c02affeb29e71

FirmwareImageFile

Type Information

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 for of this particular firmware image

status
string, one of [incompletecompleteinvalid_signatureprocessing_failuremalformed_contentdevice_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

Examples

  • 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 for of this particular firmware image

channel
ReleaseChannel (string), one of [stablefeature] , 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

Examples

  • 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 for of this particular 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

Examples

  • 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 [stablefeature] , 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.

Examples

  • Example
    {
      "release_channel": "stable"
    }

FirmwareVersion

version of a firmware

Type Information

Examples

  • Example
    v2.3.42

HashDigest

unique identifier (hexadecimal digest string)

Type Information

HashDigest (string), pattern: ^[a-f0-9]+$

Examples

  • Example
    d985c28e03a4eb39132c02affeb29e71

HoldTime

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

Type Information

HoldTime (number), minimum: 0

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.

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.

Examples

  • 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

KeypadEventName

Input peripherals can trigger different events.

Type Information

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.

Examples

  • 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.

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.

Examples

  • Example
    {
      "locked": true,
      "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.

Examples

  • 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

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).

MacAddress

unique hardware address of a network interface

Type Information

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

Examples

  • Example
    00:01:2e:7a:dc:23

NetworkAddressConfigurationIPv4

Properties

method
string, one of [staticdhcp], 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 [staticdhcp], required

Configuration method used for the address.

NetworkAddressConfigurationIPv4Static

Static address configuration does not depend on network infrastructure.

Properties

method
string, one of [staticdhcp], 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 [staticdhcpauto], 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 [staticdhcpauto], 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 [staticdhcpauto], required

Configuration method used for the address.

NetworkAddressConfigurationIPv6Static

Static address configuration does not depend on network infrastructure.

Properties

method
string, one of [staticdhcpauto], 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

Examples

  • Example
    192.168.1.100

NetworkAddressIPv6

Type Information

Examples

  • Example
    fda0:576b:c643:100:40f:10ff:fe02:e6f

NetworkInterfaceAddressConfigurationInformation

Properties

ipv4

IPv4 Network address configuration

ipv4
address_configurations
NetworkAddressConfigurationIPv4Static[]
method
string, one of [staticdhcp], 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 [staticdhcp], required

Configuration method used for the address.

current_addresses
WrappedNetworkInterfaceAddressIPv4[]
address
NetworkInterfaceAddressIPv4 (string), required

IPv4 network address in CIDR notation

ipv6

IPv6 Network address configuration

ipv6
address_configurations
NetworkAddressConfigurationIPv6Static[]
method
string, one of [staticdhcpauto], 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 [staticdhcpauto], required

Configuration method used for the address.

NetworkAddressConfigurationIPv6Auto[]
method
string, one of [staticdhcpauto], required

Configuration method used for the address.

current_addresses
WrappedNetworkInterfaceAddressIPv6[]
address
NetworkInterfaceAddressIPv6 (string), required

IPv6 network address in CIDR notation

NetworkInterfaceAddressConfigurationIPv4

Type Information

NetworkInterfaceAddressConfigurationIPv6

Type Information

NetworkInterfaceAddressConfigurationState

Configurable network address configuration of a network interface

Properties

ipv4

IPv4 Network address configuration

ipv4
address_configurations
NetworkAddressConfigurationIPv4Static[]
method
string, one of [staticdhcp], 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 [staticdhcp], required

Configuration method used for the address.

ipv6

IPv6 Network address configuration

ipv6
address_configurations
NetworkAddressConfigurationIPv6Static[]
method
string, one of [staticdhcpauto], 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 [staticdhcpauto], required

Configuration method used for the address.

NetworkAddressConfigurationIPv6Auto[]
method
string, one of [staticdhcpauto], required

Configuration method used for the address.

Examples

  • 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
WrappedNetworkInterfaceAddressIPv4[]
address
NetworkInterfaceAddressIPv4 (string), required

IPv4 network address in CIDR notation

NetworkInterfaceAddressesIPv6

Properties

current_addresses
WrappedNetworkInterfaceAddressIPv6[]
address
NetworkInterfaceAddressIPv6 (string), required

IPv6 network address in CIDR notation

NetworkInterfaceAddressFamilyInformationIPv4

IPv4 Network address configuration

Properties

address_configurations
NetworkAddressConfigurationIPv4Static[]
method
string, one of [staticdhcp], 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 [staticdhcp], required

Configuration method used for the address.

current_addresses
WrappedNetworkInterfaceAddressIPv4[]
address
NetworkInterfaceAddressIPv4 (string), required

IPv4 network address in CIDR notation

Examples

  • 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
NetworkAddressConfigurationIPv6Static[]
method
string, one of [staticdhcpauto], 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 [staticdhcpauto], required

Configuration method used for the address.

NetworkAddressConfigurationIPv6Auto[]
method
string, one of [staticdhcpauto], required

Configuration method used for the address.

current_addresses
WrappedNetworkInterfaceAddressIPv6[]
address
NetworkInterfaceAddressIPv6 (string), required

IPv6 network address in CIDR notation

Examples

  • 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
NetworkAddressConfigurationIPv4Static[]
method
string, one of [staticdhcp], 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 [staticdhcp], required

Configuration method used for the address.

NetworkInterfaceAddressFamilyStateIPv6

IPv6 Network address configuration

Properties

address_configurations
NetworkAddressConfigurationIPv6Static[]
method
string, one of [staticdhcpauto], 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 [staticdhcpauto], required

Configuration method used for the address.

NetworkAddressConfigurationIPv6Auto[]
method
string, one of [staticdhcpauto], required

Configuration method used for the address.

NetworkInterfaceAddressIPv4

IPv4 network address in CIDR notation

Type Information

Examples

  • Example
    192.168.1.100/24

NetworkInterfaceAddressIPv6

IPv6 network address in CIDR notation

Type Information

Examples

  • 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

IPv4 Network address configuration

ipv4
address_configurations
NetworkAddressConfigurationIPv4Static[]
method
string, one of [staticdhcp], 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 [staticdhcp], required

Configuration method used for the address.

ipv6

IPv6 Network address configuration

ipv6
address_configurations
NetworkAddressConfigurationIPv6Static[]
method
string, one of [staticdhcpauto], 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 [staticdhcpauto], required

Configuration method used for the address.

NetworkAddressConfigurationIPv6Auto[]
method
string, one of [staticdhcpauto], required

Configuration method used for the address.

Examples

  • 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-]+$

Examples

  • 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 [stablefeature] , default: stable

Examples

  • 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.

The only modifiable attribute within the Sampling Settings is the averages value. It is safe to change it, even though the default values calculated during an autogain operation should be optimal for most detection tasks.

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.

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).

Examples

  • 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
    }

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 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.

Examples

  • 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"]}}
      ],
      "settings_categories": [
        "access",
        "defaults",
        "emitters",
        "firmware",
        "keypad",
        "network",
        "outputs",
        "sensor",
        "system"
      ]
    }
    

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

Examples

  • Example
    [
      "Africa/Casablanca",
      "Antarctica/Troll",
      "Europe/Berlin",
      "UTC"
    ]

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

Examples

  • 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

Examples

  • 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

Examples

  • 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

Examples

  • 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)

Examples

  • 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

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

Examples

  • 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

Examples

  • 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.

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

Examples

  • 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.

Examples

  • 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-]+$

Examples

  • 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

Examples

  • 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