package blickfeld.protocol

Get desktop application:
View/edit binary Protocol Buffers messages

* > Introduced in BSL v2.14 and firmware v1.14 Describes a constraint for a single target field

Used in: Error.InvalidRequest, Response.GetScanPatternConstraints, config.ScanPattern

• optional Field target = 1

  Link to target field on which the contraint is applied

• optional string reason = 2

  Human-readable reason for the constraint and its failure

• oneof type

  • Constraint.Constant constant = 10

  • Constraint.Polynomial polynomial = 11

Constant constraint which is used to apply min and/or max ranges

Used in: Constraint

• optional float minimum = 1

  Target value must be equals or higher than the specified minimum

• optional float maximum = 2

  Target value must be equals or smaller than the specified maximum

Polynomial constraint which describe a value relationship to another field

Used in: Constraint

• optional Field reference = 1

  Link to reference field. The value of the reference field is used as x input for the polynomial.

• repeated float minimum = 2

  Target value must be equals or higher than the specified minimum, which is described by the specified repeated coefficients: c0 + x * c1 + x^2 * c2 ..

• repeated float maximum = 3

  Target value must be equals or smaller than the specified maximum, which is described by the specified repeated coefficients: c0 + x * c1 + x^2 * c2 ..

Used in: Response, status.Scanner

• oneof error

  • Error.Unknown unknown = 1

    Refer to [Unknown](#blickfeld.protocol.Error.Unknown)

  • Error.NotImplemented not_implemented = 2

    Refer to [NotImplemented](#blickfeld.protocol.Error.NotImplemented)

  • Error.Empty empty = 3

    Refer to [Empty](#blickfeld.protocol.Error.Empty)

  • Error.ServerImplementation server_implementation = 4

    Refer to [ServerImplementation](#blickfeld.protocol.Error.ServerImplementation)

  • Error.InvalidRequest invalid_request = 5

    Refer to [InvalidRequest](#blickfeld.protocol.Error.InvalidRequest)

  • Error.ConnectionClosed connection_closed = 6

    Refer to [ConnectionClosed](#blickfeld.protocol.Error.ConnectionClosed)

  • Error.OutdatedServerProtocol outdated_server_protocol = 11

    Refer to [OutdatedServerProtocol](#blickfeld.protocol.Error.OutdatedServerProtocol)

  • Error.OutdatedClientProtocol outdated_client_protocol = 12

    Refer to [OutdatedClientProtocol](#blickfeld.protocol.Error.OutdatedClientProtocol)

  • Error.ScannerBusy scanner_busy = 13

    Refer to [ScannerBusy](#blickfeld.protocol.Error.ScannerBusy)

  • Error.WrongOperationMode wrong_operation_mode = 14

    Refer to [WrongOperationMode](#blickfeld.protocol.Error.WrongOperationMode)

  • Error.NotAllowed not_allowed = 15

    Refer to [NotAllowed](#blickfeld.protocol.Error.NotAllowed)

  • Error.HardwareError hardware_error = 16

    Refer to [HardwareError](#blickfeld.protocol.Error.HardwareError)

  • Error.SystemStop system_stop = 17

    Refer to [SystemStop](#blickfeld.protocol.Error.SystemStop)

  • Error.NotFound not_found = 18

    Refer to [NotFound](#blickfeld.protocol.Error.NotFound)

  • Error.UnknownErrorCode unknown_error_code = 21

    Refer to [UnknownErrorCode](#blickfeld.protocol.Error.UnknownErrorCode)

  • Error.NotInRange not_in_range = 22

    Refer to [NotInRange](#blickfeld.protocol.Error.NotInRange)

  • Error.TimeSyncFailed time_sync_failed = 23

    Refer to [TimeSyncFailed](#blickfeld.protocol.Error.TimeSyncFailed)

  • Error.NoDeviceDiscovered no_device_discovered = 24

    Refer to [NoDeviceDiscovered](#blickfeld.protocol.Error.NoDeviceDiscovered)

  • Error.NotSupported not_supported = 25

    Refer to [NotSupported](#blickfeld.protocol.Error.NotSupported)

  • Error.ConnectionAbort connection_abort = 26

    Refer to [ConnectionAbort](#blickfeld.protocol.Error.ConnectionAbort)

* During reading, the connection to the device got aborted.

Used in: Error

• optional string details = 1

* The server closed the connection.

Used in: Error

(message has no fields)

* The server sent an empty message.

Used in: Error

(message has no fields)

* The device is in an error state and cannot be operated. Attempt to power-cycle the device or use diagnostic software to read out the hardware state.

Used in: Error

(message has no fields)

* Validation of the sent request failed, please send a request with-in a valid range.

Used in: Error

• optional string validation_error = 1

  Validation error string

• repeated Constraint constraints = 2

  <blockquote>Introduced in BSL v2.14 and firmware v1.14</blockquote> Contains list of failed constraints. The `validation_error` field contains a human-readable output of the constraint validation.

* No device has been discovered. Check the network connection and power supply of the device. The 'discover' requests may have been blocked by a local or a network firewall.

Used in: Error

(message has no fields)

* The requested operation is not allowed.

Used in: Error

(message has no fields)

* The requested data is not available. Please check the request parameters.

Used in: Error

(message has no fields)

* The firmware on the device is not compatible with the BSL version. Update the device or downgrade the BSL.

Used in: Error

• optional string reason = 1

  Description why this is not implemented

* The requested parameter is not within the valid range.

Used in: Error

• optional string parameter = 1

  The parameter, which was not in range

• optional float minimum = 2

  Minimum value of the parameter

• optional float maximum = 3

  Maximum value of the parameter

• optional float requested = 4

  Requested value of the parameter

• optional string unit = 5

  Unit of the parameter

* The action is not supported by the current client or server API. Check the versions of the client and firmware software and read the changelog.

Used in: Error

• optional string reason = 1

  Description why this is not supported

* The protocol of the server is too new. Please update the client software.

Used in: Error

• optional uint32 required_version = 1

  Version that is required

* The protocol of the client is too new. Please update the device.

Used in: Error

• optional uint32 required_version = 1

  Version that is required

* The device is currently busy with another operation. Cancel it and try again.

Used in: Error

(message has no fields)

* The server failed to process the request.

Used in: Error

(message has no fields)

* The device stopped unexpectedly and can no longer be operated. Attempt to power cycle the device or use diagnostic software to read-out the hardware state.

Used in: Error

(message has no fields)

* The time synchronization failed. The NTP daemon failed or timed out.

Used in: Error

• optional string ntp_daemon_log = 1

  Log of the NTP daemon

* Unknown error. Please consult the Blickfeld support team for further information.

Used in: Error

• optional string description = 1

  Description of the unknown error

* Unknown Error. Please contact the Blickfeld support team and make sure to use compatible BSL and FW versions.

Used in: Error

• optional uint32 error_code = 1

  Error code

* The device is set to a different operation mode. Perhaps it is currently being used by another application. Change the operation mode and try again if no one else is using it.

Used in: Error

(message has no fields)

* > Introduced in BSL v2.14 and firmware v1.14 Describes a protobuf field inside a (nested) message to efficiently use reflection on all supported platforms

Used in: Constraint, Constraint.Polynomial

• repeated Field.Identifier identifiers = 1

  Path to field in relation to given top level message.

• optional float scale = 2

  Numerical scale which is applied on a field value before using it for validation. This is required to prevent floating point precision issues due to rounding, which could fail a validation.<br> Validation example: Field value is stored as radian but is shown to the user as degree. Without scaling and rounding, a possible degree format could be rejected as it exceeded the maximum value of the radian respresentation after down-scaling.

Describes unique identifier of (sub) field

Used in: Field

• optional uint32 id = 1

  Protobuf number of field

• optional string key = 2

  Protobuf key of field

• optional string camelcase_key = 3

  Protobuf camelcase key of field

* The format type of response is an undocumented, internal feature required for the REST API.

Used in: Request

• PROTOBUF = 1

• JSON = 2

Used in: Response.Hello

• optional string serial_number = 1

  Serial number of the hardware module

• optional string legacy_serial_number = 2

  Deprecated legacy serial number format

• optional string version = 3

  Hardware version of the hardware module if available.

Used in: Request.Hello, Response.Hello, file.Client

• CPP = 1

• PYTHON = 2

• TYPESCRIPT = 3

Used in: config.ScanPattern.Filter

• optional float minimum = 1

• optional float maximum = 2

* This section describes the different requests a client can send to the server. A request is always answered with a response. For every response, there is a request with the same name.

• oneof data

  • Request.Hello hello = 11

    Refer to [Request.Hello](#blickfeld.protocol.Request.Hello)

  • Request.Developer developer = 13

    Refer to [Request.Developer](#blickfeld.protocol.Request.Developer)

  • Request.SetScanPattern set_scan_pattern = 15

    Refer to [Request.SetScanPattern](#blickfeld.protocol.Request.SetScanPattern)

  • Request.FillScanPattern fill_scan_pattern = 16

    Refer to [Request.FillScanPattern](#blickfeld.protocol.Request.FillScanPattern)

  • Request.GetScanPattern get_scan_pattern = 17

    Refer to [Request.GetScanPattern](#blickfeld.protocol.Request.GetScanPattern)

  • stream.Subscribe subscribe = 18

    Refer to [Subscribe](#blickfeld.protocol.stream.Subscribe)

  • Request.Status status = 19

    Refer to [Request.Status](#blickfeld.protocol.Request.Status)

  • Request.RunSelfTest run_self_test = 20

    Refer to [Request.RunSelfTest](#blickfeld.protocol.Request.RunSelfTest)

  • Request.SetAdvancedConfig set_advanced_config = 21

    <blockquote>Introduced in BSL v2.11 and firmware v1.11</blockquote> Refer to [Request.SetAdvancedConfig](#blickfeld.protocol.Request.SetAdvancedConfig)

  • Request.GetAdvancedConfig get_advanced_config = 22

    <blockquote>Introduced in BSL v2.11 and firmware v1.11</blockquote> Refer to [Request.GetAdvancedConfig](#blickfeld.protocol.Request.GetAdvancedConfig)

  • stream.Subscribe unsubscribe = 23

    <blockquote>Introduced in BSL v2.13 and firmware v1.13</blockquote> Unsubscribe a stream started with a [Subscribe](#blickfeld.protocol.stream.Subscribe) request.

  • Request.AttemptErrorRecovery attempt_error_recovery = 24

    <blockquote>Introduced in BSL v2.13 and firmware v1.13</blockquote> Refer to [Request.AttemptErrorRecovery](#blickfeld.protocol.Request.AttemptErrorRecovery)

  • Request.GetScanPatternConstraints get_scan_pattern_constraints = 25

    <blockquote>Introduced in BSL v2.14 and firmware v1.14</blockquote> Refer to [Request.GetScanPatternConstraints](#blickfeld.protocol.Request.GetScanPatternConstraints)

  • Request.GetNamedScanPatterns get_named_scan_patterns = 26

    <blockquote>Introduced in BSL v2.15 and firmware v1.16</blockquote> Refer to [Request.GetNamedScanPatterns](#blickfeld.protocol.Request.GetNamedScanPatterns)

  • Request.StoreNamedScanPattern store_named_scan_pattern = 27

    <blockquote>Introduced in BSL v2.15 and firmware v1.16</blockquote> Refer to [Request.StoreNamedScanPattern](#blickfeld.protocol.Request.StoreNamedScanPattern)

  • Request.DeleteNamedScanPattern delete_named_scan_pattern = 28

    <blockquote>Introduced in BSL v2.15 and firmware v1.16</blockquote> Refer to [Request.DeleteNamedScanPattern](#blickfeld.protocol.Request.DeleteNamedScanPattern)

  • Request.ProxyHello proxy_hello = 29

    <blockquote>Introduced in BSL v2.16 and firmware v1.17</blockquote> Refer to [Request.ProxyHello](#blickfeld.protocol.Request.ProxyHello)

  • string _asJSON = 100

    Internal use only

• optional Format accept_format = 101

  Internal use only

* > Introduced in BSL v2.13 and firmware v1.13 This request can be used to attempt a re-initialization of the device if it is errored. A self test is automatically triggered after a successful re-initialization.

Used in: Request

(message has no fields)

* > Introduced in BSL v2.15 and firmware v1.16 This request deletes a named scan pattern. Default scan patterns can't be deleted.

Used in: Request

• optional string name = 1

  Name

* Internal use only

Used in: Request

(message has no fields)

* This request is used to fill an empty or partially filled scan pattern with the required parameters. It will fill the given scan pattern with default values and return the filled scan pattern to the client. The filled scan pattern can then be set as input for [Request.SetScanPattern](#blickfeld.protocol.Request.SetScanPattern).

Used in: Request

• optional config.ScanPattern config = 2

  Refer to [ScanPattern](#blickfeld.protocol.config.ScanPattern)

* > Introduced in BSL v2.11 and firmware v1.11 This request is used to retrieve the currently set [Advanced](#blickfeld.protocol.config.Advanced).

Used in: Request

(message has no fields)

* > Introduced in BSL v2.15 and firmware v1.16 This request returns a list of named scan patterns.

Used in: Request

(message has no fields)

* This request is used to retrieve the currently set [ScanPattern](#blickfeld.protocol.config.ScanPattern).

Used in: Request

(message has no fields)

* > Introduced in BSL v2.14 and firmware v1.14 This request returns a list of constraints which are applied on scan patterns. The constraints define the constant and dynamic relationships between field values. The constraints are equal for a device type and firmware, but might vary for firmware releases and device variants. It is mainly used to visualize the constraints in the scan pattern configuration of the web gui.

Used in: Request

(message has no fields)

* This request is used for initial communication after connecting to a device and testing the established connection.

Used in: Request

• optional uint32 protocol_version = 1

  Version of the Blickfeld protocol

• optional string library_version = 2

  <blockquote>Introduced in BSL v2.16 and firmware v1.17</blockquote> Library version

• optional Language language = 3

  <blockquote>Introduced in BSL v2.16 and firmware v1.17</blockquote> Library language

* Internal use only This request is used by internal proxy implementation to forward the correct ip address to the server.

Used in: Request

• optional string ip_address = 1

  IP address of the real client

* > Introduced in BSL v2.10 and firmware v1.9 This request triggers a self test of the device. It validates the hardware, operates the device, and generates a report. The report is currently only accessible by developers.

Used in: Request

(message has no fields)

* > Introduced in BSL v2.11 and firmware v1.11 This request is used for configuring the advanced config.

Used in: Request

• optional config.Advanced config = 1

  Refer to [Advanced](#blickfeld.protocol.config.Advanced)

• optional bool persist = 2

  Persists the config and sets it after a power cycle. Default: True

* This request is used for setting a Scan Pattern. A Scan Pattern can either be set by providing a Scan Pattern configuration or a name of a named Scan Pattern.

Used in: Request

• oneof data

  • config.ScanPattern config = 3

    Refer to [ScanPattern](#blickfeld.protocol.config.ScanPattern)

  • string name = 4

    Set named Scan Pattern, refer to [NamedScanPattern](#blickfeld.protocol.config.NamedScanPattern)

• optional bool persist = 2

  Persists the scan pattern and sets it after a power cycle. Default: False

* This request is used for receiving the current [Status](#blickfeld.protocol.status.Status).

Used in: Request

(message has no fields)

* > Introduced in BSL v2.15 and firmware v1.16 This request sets a named scan patterns. The name has to be different of the default scan patterns and can only contain letters, numbers, space, underscore and minus.

Used in: Request

• optional string name = 1

  Name

• optional config.ScanPattern config = 2

  Refer to [ScanPattern](#blickfeld.protocol.config.ScanPattern)

* This section describes the responses a client receives after sending a request to the server. For the request that corresponds to a given response, please refer to [Request](#blickfeld.protocol.Request). Each response has the same name as the request.

• optional uint64 timestamp_ns = 1

  Unit: [ns] - timestamp when the response is sent out

• oneof data

  • Error error = 10

    Refer to [Error](#blickfeld.protocol.Error)

  • Response.Hello hello = 11

    Refer to [Response.Hello](#blickfeld.protocol.Response.Hello)

  • Response.Developer developer = 13

    Refer to [Response.Developer](#blickfeld.protocol.Response.Developer)

  • Response.SetScanPattern set_scan_pattern = 15

    Refer to [Response.SetScanPattern](#blickfeld.protocol.Response.SetScanPattern)

  • Response.FillScanPattern fill_scan_pattern = 16

    Refer to [Response.FillScanPattern](#blickfeld.protocol.Response.FillScanPattern)

  • Response.GetScanPattern get_scan_pattern = 17

    Refer to [Response.GetScanPattern](#blickfeld.protocol.Response.GetScanPattern)

  • stream.Event event = 18

    Refer to [Event](#blickfeld.protocol.stream.Event)

  • Status status = 19

    Refer to [Response.Status](#blickfeld.protocol.Response.Status)

  • Response.RunSelfTest run_self_test = 20

    Refer to [Response.RunSelfTest](#blickfeld.protocol.Response.RunSelfTest)

  • Response.SetAdvancedConfig set_advanced_config = 21

    <blockquote>Introduced in BSL v2.11 and firmware v1.11</blockquote> Refer to [Response.SetAdvanced](#blickfeld.protocol.Response.SetAdvancedConfig)

  • Response.GetAdvancedConfig get_advanced_config = 22

    <blockquote>Introduced in BSL v2.11 and firmware v1.11</blockquote> Refer to [Response.GetAdvanced](#blickfeld.protocol.Response.GetAdvancedConfig)

  • Response.AttemptErrorRecovery attempt_error_recovery = 24

    <blockquote>Introduced in BSL v2.13 and firmware v1.13</blockquote> Refer to [Response.AttemptErrorRecovery](#blickfeld.protocol.Response.AttemptErrorRecovery)

  • Response.GetScanPatternConstraints get_scan_pattern_constraints = 25

    <blockquote>Introduced in BSL v2.14 and firmware v1.14</blockquote> Refer to [Response.GetScanPatternConstraints](#blickfeld.protocol.Response.GetScanPatternConstraints)

  • Response.GetNamedScanPatterns get_named_scan_patterns = 26

    <blockquote>Introduced in BSL v2.15 and firmware v1.16</blockquote> Refer to [Response.GetNamedScanPatterns](#blickfeld.protocol.Response.GetNamedScanPatterns)

  • Response.StoreNamedScanPattern store_named_scan_pattern = 27

    <blockquote>Introduced in BSL v2.15 and firmware v1.16</blockquote> Refer to [Response.StoreNamedScanPattern](#blickfeld.protocol.Response.StoreNamedScanPattern)

  • Response.DeleteNamedScanPattern delete_named_scan_pattern = 28

    <blockquote>Introduced in BSL v2.15 and firmware v1.16</blockquote> Refer to [Response.DeleteNamedScanPattern](#blickfeld.protocol.Response.DeleteNamedScanPattern)

  • Response.ProxyHello proxy_hello = 29

    <blockquote>Introduced in BSL v2.16 and firmware v1.17</blockquote> Refer to [Response.ProxyHello](#blickfeld.protocol.Response.ProxyHello)

  • string _asJSON = 100

    Internal use only

* > Introduced in BSL v2.13 and firmware v1.13 This response is sent out after sending AttemptErrorRecovery.

Used in: Response

(message has no fields)

* > Introduced in BSL v2.15 and firmware v1.16 This response is sent out after sending DeleteNamedScanPattern.

Used in: Response

(message has no fields)

* Internal use only

Used in: Response

(message has no fields)

* This response is given after a request to fill a sparse [ScanPattern](#blickfeld.protocol.config.ScanPattern) has been transmitted. It returns a scan pattern, the unset fields are filled with default values.

Used in: Response

• optional config.ScanPattern config = 2

  Refer to [ScanPattern](#blickfeld.protocol.config.ScanPattern)

* > Introduced in BSL v2.11 and firmware v1.11 This response is returned after a request to get the current [Advanced](#blickfeld.protocol.config.Advanced).

Used in: Response

• optional config.Advanced config = 1

  Refer to [Advanced](#blickfeld.protocol.config.Advanced)

* > Introduced in BSL v2.15 and firmware v1.16 This response is sent out after sending GetNamedScanPatterns.

Used in: Response

• repeated config.NamedScanPattern configs = 1

  List of named scan patterns, refer to [NamedScanPattern](#blickfeld.protocol.config.NamedScanPattern)

* This response is returned after a request to get the current [ScanPattern](#blickfeld.protocol.config.ScanPattern).

Used in: Response

• optional config.ScanPattern config = 2

  Refer to [ScanPattern](#blickfeld.protocol.config.ScanPattern)

* > Introduced in BSL v2.14 and firmware v1.14 This response is sent out after sending GetScanPatternConstraints.

Used in: Response

• repeated Constraint constraints = 1

  List of constraints which apply for scan patterns.

* This response is sent out after establishing a connection.

Used in: Response

• optional uint32 protocol_version = 1

  Version of the Blickfeld Protocol

• optional string library_version = 2

  <blockquote>Introduced in BSL v2.16 and firmware v1.17</blockquote> Library version

• optional Language language = 3

  <blockquote>Introduced in BSL v2.16 and firmware v1.17</blockquote> Library language

• optional config.Product product = 4

  <blockquote>Introduced in BSL v2.16 and firmware v1.17</blockquote> Refer to [Product](#blickfeld.protocol.config.Product).

• oneof oneof_serial_number

  • string serial_number = 5

    <blockquote>Introduced in BSL v2.16 and firmware v1.17</blockquote> Cube serial number

  • string legacy_serial_number = 6

    <blockquote>Introduced in BSL v2.16 and firmware v1.17</blockquote> Deprecated legacy serial number

• optional Hello.Firmware firmware = 7

  <blockquote>Introduced in BSL v2.16 and firmware v1.17</blockquote> Refer to [Firmware](#blickfeld.protocol.Response.Hello.Firmware).

• map<string, HardwareModule> hardware_modules = 8

  <blockquote>Introduced in BSL v2.16 and firmware v1.17</blockquote> Hardware module map, where the key is the name and the object is the [HardwareModule](#blickfeld.protocol.HardwareModule).

* > Introduced in BSL v2.16 and firmware v1.17 Contains all firmware names, versions, and revisions.

Used in: Hello

• optional SoftwareVersion version = 1

  Baseline version of firmware. Refer to [SoftwareVersion](#blickfeld.protocol.SoftwareVersion).

• map<string, SoftwareVersion> module_versions = 2

  Version of software modules. The key of the map is the name and the object is the [SoftwareVersion](#blickfeld.protocol.SoftwareVersion).

* Internal use only

Used in: Response

(message has no fields)

* > Introduced in BSL v2.10 and firmware v1.9 This response is returned after a self test. The success flag indicates if the hardware is fully operational. The generated report is currently only accessible by developers.

Used in: Response

• optional bool success = 1

* > Introduced in BSL v2.11 and firmware v1.11 This response is sent out after setting an SetAdvancedConfig.

Used in: Response

(message has no fields)

* This response is sent out after setting a scan pattern.

Used in: Response

(message has no fields)

* > Introduced in BSL v2.15 and firmware v1.16 This response is sent out after sending StoreNamedScanPattern.

Used in: Response

(message has no fields)

Used in: Response.Hello.Firmware

• optional string name = 1

  Tag or reference name of the version. It is not the the name of the software.

• optional string revision = 2

  The GIT revision of the software version if available.

• optional uint32 ci_job_id = 3

  The unique continuous integration job ID if available.

* This section contains the status messages of the two deflection mirrors and the temperature sensors in the device.

Used in: Response, stream.Event

• optional status.Scanner scanner = 1

  Refer to [Scanner](#blickfeld.protocol.status.scanner.Scanner)

• repeated status.Temperature temperatures = 2

  Refer to [Temperature](#blickfeld.protocol.status.temperature.Temperature)

• optional status.Server server = 5

  Refer to [Client](#blickfeld.protocol.status.server.Server)

• optional status.IMU imu = 7

  <blockquote>Introduced in BSL v2.18 and firmware v1.19</blockquote> Refer to [IMU](#blickfeld.protocol.status.IMU)

• optional status.TimeSynchronization time_synchronization = 8

  <blockquote>Introduced in BSL v2.18 and firmware v1.19</blockquote> Refer to [TimeSynchronization](#blickfeld.protocol.status.TimeSynchronization)

• optional float minimum = 1

• optional float maximum = 2