Protobuf definitions

This is the documentation of the protobuf messages used by the Blickfeld API.

These protobuf messages are used to communicate with Blickfeld devices. You can send requests and receive responses. The corresponding response to a request has the same name. It is also possible to request a point cloud stream or a status stream.

The data, such as a point cloud, are also packed in protobuf messages.

Table of Contents

Top

blickfeld/common.proto

Constraint

Introduced in BSL v2.14 and firmware v1.14

Describes a constraint for a single target field

Field Type Label Description
target Field optional Link to target field on which the contraint is applied
reason string optional Human-readable reason for the constraint and its failure
constant Constraint.Constant optional
polynomial Constraint.Polynomial optional

Constraint.Constant

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

Field Type Label Description
minimum float optional Target value must be equals or higher than the specified minimum
maximum float optional Target value must be equals or smaller than the specified maximum

Constraint.Polynomial

Polynomial constraint which describe a value relationship to another field

Field Type Label Description
reference Field optional Link to reference field. The value of the reference field is used as x input for the polynomial.
minimum float repeated 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 ..
maximum float repeated 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 ..

Field

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

Field Type Label Description
identifiers Field.Identifier repeated Path to field in relation to given top level message.
scale float optional 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.
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.

Field.Identifier

Describes unique identifier of (sub) field

Field Type Label Description
id uint32 optional Protobuf number of field
key string optional Protobuf key of field
camelcase_key string optional Protobuf camelcase key of field

HardwareModule

Field Type Label Description
serial_number string optional Serial number of the hardware module
legacy_serial_number string optional Deprecated legacy serial number format
version string optional Hardware version of the hardware module if available.

OptionalValueRange

Field Type Label Description
minimum float optional
maximum float optional

SoftwareVersion

Field Type Label Description
name string optional Tag or reference name of the version. It is not the the name of the software.
revision string optional The GIT revision of the software version if available.
ci_job_id uint32 optional The unique continuous integration job ID if available.

ValueRange

Field Type Label Description
minimum float optional
maximum float optional

Language

Name Number Description
CPP 1
PYTHON 2
TYPESCRIPT 3

Top

blickfeld/connection.proto

Request

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.

Field Type Label Description
hello Request.Hello optional Refer to Request.Hello
developer Request.Developer optional Refer to Request.Developer
set_scan_pattern Request.SetScanPattern optional Refer to Request.SetScanPattern
fill_scan_pattern Request.FillScanPattern optional Refer to Request.FillScanPattern
get_scan_pattern Request.GetScanPattern optional Refer to Request.GetScanPattern
subscribe stream.Subscribe optional Refer to Subscribe
status Request.Status optional Refer to Request.Status
run_self_test Request.RunSelfTest optional Refer to Request.RunSelfTest
set_advanced_config Request.SetAdvancedConfig optional
Introduced in BSL v2.11 and firmware v1.11
Refer to Request.SetAdvancedConfig
get_advanced_config Request.GetAdvancedConfig optional
Introduced in BSL v2.11 and firmware v1.11
Refer to Request.GetAdvancedConfig
unsubscribe stream.Subscribe optional
Introduced in BSL v2.13 and firmware v1.13
Unsubscribe a stream started with a Subscribe request.
attempt_error_recovery Request.AttemptErrorRecovery optional
Introduced in BSL v2.13 and firmware v1.13
Refer to Request.AttemptErrorRecovery
get_scan_pattern_constraints Request.GetScanPatternConstraints optional
Introduced in BSL v2.14 and firmware v1.14
Refer to Request.GetScanPatternConstraints
get_named_scan_patterns Request.GetNamedScanPatterns optional
Introduced in BSL v2.15 and firmware v1.16
Refer to Request.GetNamedScanPatterns
store_named_scan_pattern Request.StoreNamedScanPattern optional
Introduced in BSL v2.15 and firmware v1.16
Refer to Request.StoreNamedScanPattern
delete_named_scan_pattern Request.DeleteNamedScanPattern optional
Introduced in BSL v2.15 and firmware v1.16
Refer to Request.DeleteNamedScanPattern
proxy_hello Request.ProxyHello optional
Introduced in BSL v2.16 and firmware v1.17
Refer to Request.ProxyHello
_asJSON string optional Internal use only
accept_format Format optional Internal use only Default: PROTOBUF

Request.AttemptErrorRecovery

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.

Request.DeleteNamedScanPattern

Introduced in BSL v2.15 and firmware v1.16

This request deletes a named scan pattern. Default scan patterns can’t be deleted.

Field Type Label Description
name string optional Name

Request.Developer

Internal use only

Request.FillScanPattern

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.

Field Type Label Description
config config.ScanPattern optional Refer to ScanPattern

Request.GetAdvancedConfig

Introduced in BSL v2.11 and firmware v1.11

This request is used to retrieve the currently set Advanced.

Request.GetNamedScanPatterns

Introduced in BSL v2.15 and firmware v1.16

This request returns a list of named scan patterns.

Request.GetScanPattern

This request is used to retrieve the currently set ScanPattern.

Request.GetScanPatternConstraints

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.

Request.Hello

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

Field Type Label Description
protocol_version uint32 optional Version of the Blickfeld protocol
library_version string optional
Introduced in BSL v2.16 and firmware v1.17
Library version
language Language optional
Introduced in BSL v2.16 and firmware v1.17
Library language

Request.ProxyHello

Internal use only

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

Field Type Label Description
ip_address string optional IP address of the real client

Request.RunSelfTest

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.

Request.SetAdvancedConfig

Introduced in BSL v2.11 and firmware v1.11

This request is used for configuring the advanced config.

Field Type Label Description
config config.Advanced optional Refer to Advanced
persist bool optional Persists the config and sets it after a power cycle. Default: True Default: true

Request.SetScanPattern

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.

Field Type Label Description
config config.ScanPattern optional Refer to ScanPattern
name string optional Set named Scan Pattern, refer to NamedScanPattern
persist bool optional Persists the scan pattern and sets it after a power cycle. Default: False Default: false

Request.Status

This request is used for receiving the current Status.

Request.StoreNamedScanPattern

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.

Field Type Label Description
name string optional Name
config config.ScanPattern optional Refer to ScanPattern

Response

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. Each response has the same name as the request.

Field Type Label Description
timestamp_ns uint64 optional Unit: [ns] - timestamp when the response is sent out
error Error optional Refer to Error
hello Response.Hello optional Refer to Response.Hello
developer Response.Developer optional Refer to Response.Developer
set_scan_pattern Response.SetScanPattern optional Refer to Response.SetScanPattern
fill_scan_pattern Response.FillScanPattern optional Refer to Response.FillScanPattern
get_scan_pattern Response.GetScanPattern optional Refer to Response.GetScanPattern
event stream.Event optional Refer to Event
status Status optional Refer to Response.Status
run_self_test Response.RunSelfTest optional Refer to Response.RunSelfTest
set_advanced_config Response.SetAdvancedConfig optional
Introduced in BSL v2.11 and firmware v1.11
Refer to Response.SetAdvanced
get_advanced_config Response.GetAdvancedConfig optional
Introduced in BSL v2.11 and firmware v1.11
Refer to Response.GetAdvanced
attempt_error_recovery Response.AttemptErrorRecovery optional
Introduced in BSL v2.13 and firmware v1.13
Refer to Response.AttemptErrorRecovery
get_scan_pattern_constraints Response.GetScanPatternConstraints optional
Introduced in BSL v2.14 and firmware v1.14
Refer to Response.GetScanPatternConstraints
get_named_scan_patterns Response.GetNamedScanPatterns optional
Introduced in BSL v2.15 and firmware v1.16
Refer to Response.GetNamedScanPatterns
store_named_scan_pattern Response.StoreNamedScanPattern optional
Introduced in BSL v2.15 and firmware v1.16
Refer to Response.StoreNamedScanPattern
delete_named_scan_pattern Response.DeleteNamedScanPattern optional
Introduced in BSL v2.15 and firmware v1.16
Refer to Response.DeleteNamedScanPattern
proxy_hello Response.ProxyHello optional
Introduced in BSL v2.16 and firmware v1.17
Refer to Response.ProxyHello
_asJSON string optional Internal use only

Response.AttemptErrorRecovery

Introduced in BSL v2.13 and firmware v1.13

This response is sent out after sending AttemptErrorRecovery.

Response.DeleteNamedScanPattern

Introduced in BSL v2.15 and firmware v1.16

This response is sent out after sending DeleteNamedScanPattern.

Response.Developer

Internal use only

Response.FillScanPattern

This response is given after a request to fill a sparse ScanPattern has been transmitted. It returns a scan pattern, the unset fields are filled with default values.

Field Type Label Description
config config.ScanPattern optional Refer to ScanPattern

Response.GetAdvancedConfig

Introduced in BSL v2.11 and firmware v1.11

This response is returned after a request to get the current Advanced.

Field Type Label Description
config config.Advanced optional Refer to Advanced

Response.GetNamedScanPatterns

Introduced in BSL v2.15 and firmware v1.16

This response is sent out after sending GetNamedScanPatterns.

Field Type Label Description
configs config.NamedScanPattern repeated List of named scan patterns, refer to NamedScanPattern

Response.GetScanPattern

This response is returned after a request to get the current ScanPattern.

Field Type Label Description
config config.ScanPattern optional Refer to ScanPattern

Response.GetScanPatternConstraints

Introduced in BSL v2.14 and firmware v1.14

This response is sent out after sending GetScanPatternConstraints.

Field Type Label Description
constraints Constraint repeated List of constraints which apply for scan patterns.

Response.Hello

This response is sent out after establishing a connection.

Field Type Label Description
protocol_version uint32 optional Version of the Blickfeld Protocol
library_version string optional
Introduced in BSL v2.16 and firmware v1.17
Library version
language Language optional
Introduced in BSL v2.16 and firmware v1.17
Library language
product config.Product optional
Introduced in BSL v2.16 and firmware v1.17
Refer to Product.
serial_number string optional
Introduced in BSL v2.16 and firmware v1.17
Cube serial number
legacy_serial_number string optional
Introduced in BSL v2.16 and firmware v1.17
Deprecated legacy serial number
firmware Response.Hello.Firmware optional
Introduced in BSL v2.16 and firmware v1.17
Refer to Firmware.
hardware_modules Response.Hello.HardwareModulesEntry repeated
Introduced in BSL v2.16 and firmware v1.17
Hardware module map, where the key is the name and the object is the HardwareModule.

Response.Hello.Firmware

Introduced in BSL v2.16 and firmware v1.17

Contains all firmware names, versions, and revisions.

Field Type Label Description
version SoftwareVersion optional Baseline version of firmware. Refer to SoftwareVersion.
module_versions Response.Hello.Firmware.ModuleVersionsEntry repeated Version of software modules. The key of the map is the name and the object is the SoftwareVersion.

Response.Hello.Firmware.ModuleVersionsEntry

Field Type Label Description
key string optional
value SoftwareVersion optional

Response.Hello.HardwareModulesEntry

Field Type Label Description
key string optional
value HardwareModule optional

Response.ProxyHello

Internal use only

Response.RunSelfTest

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.

Field Type Label Description
success bool optional

Response.SetAdvancedConfig

Introduced in BSL v2.11 and firmware v1.11

This response is sent out after setting an SetAdvancedConfig.

Response.SetScanPattern

This response is sent out after setting a scan pattern.

Response.StoreNamedScanPattern

Introduced in BSL v2.15 and firmware v1.16

This response is sent out after sending StoreNamedScanPattern.

Format

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

Name Number Description
PROTOBUF 1
JSON 2

Top

blickfeld/error.proto

Error

Field Type Label Description
unknown Error.Unknown optional Refer to Unknown
not_implemented Error.NotImplemented optional Refer to NotImplemented
empty Error.Empty optional Refer to Empty
server_implementation Error.ServerImplementation optional Refer to ServerImplementation
invalid_request Error.InvalidRequest optional Refer to InvalidRequest
connection_closed Error.ConnectionClosed optional Refer to ConnectionClosed
outdated_server_protocol Error.OutdatedServerProtocol optional Refer to OutdatedServerProtocol
outdated_client_protocol Error.OutdatedClientProtocol optional Refer to OutdatedClientProtocol
scanner_busy Error.ScannerBusy optional Refer to ScannerBusy
wrong_operation_mode Error.WrongOperationMode optional Refer to WrongOperationMode
not_allowed Error.NotAllowed optional Refer to NotAllowed
hardware_error Error.HardwareError optional Refer to HardwareError
system_stop Error.SystemStop optional Refer to SystemStop
not_found Error.NotFound optional Refer to NotFound
unknown_error_code Error.UnknownErrorCode optional Refer to UnknownErrorCode
not_in_range Error.NotInRange optional Refer to NotInRange
time_sync_failed Error.TimeSyncFailed optional Refer to TimeSyncFailed
no_device_discovered Error.NoDeviceDiscovered optional Refer to NoDeviceDiscovered
not_supported Error.NotSupported optional Refer to NotSupported
connection_abort Error.ConnectionAbort optional Refer to ConnectionAbort

Error.ConnectionAbort

During reading, the connection to the device got aborted.

Field Type Label Description
details string optional

Error.ConnectionClosed

The server closed the connection.

Error.Empty

The server sent an empty message.

Error.HardwareError

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.

Error.InvalidRequest

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

Field Type Label Description
validation_error string optional Validation error string
constraints Constraint repeated
Introduced in BSL v2.14 and firmware v1.14
Contains list of failed constraints. The validation_error field contains a human-readable output of the constraint validation.

Error.NoDeviceDiscovered

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.

Error.NotAllowed

The requested operation is not allowed.

Error.NotFound

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

Error.NotImplemented

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

Field Type Label Description
reason string optional Description why this is not implemented Default: No detailed reason available.

Error.NotInRange

The requested parameter is not within the valid range.

Field Type Label Description
parameter string optional The parameter, which was not in range
minimum float optional Minimum value of the parameter
maximum float optional Maximum value of the parameter
requested float optional Requested value of the parameter
unit string optional Unit of the parameter

Error.NotSupported

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.

Field Type Label Description
reason string optional Description why this is not supported Default: No detailed reason available.

Error.OutdatedClientProtocol

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

Field Type Label Description
required_version uint32 optional Version that is required

Error.OutdatedServerProtocol

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

Field Type Label Description
required_version uint32 optional Version that is required

Error.ScannerBusy

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

Error.ServerImplementation

The server failed to process the request.

Error.SystemStop

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.

Error.TimeSyncFailed

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

Field Type Label Description
ntp_daemon_log string optional Log of the NTP daemon

Error.Unknown

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

Field Type Label Description
description string optional Description of the unknown error

Error.UnknownErrorCode

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

Field Type Label Description
error_code uint32 optional Error code

Error.WrongOperationMode

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.

Top

blickfeld/options.proto

File-level Extensions

| Extension | Type | Base | Number | Description | | ——— | —- | —- | —— | ———– | | allow_sparse | bool | .google.protobuf.FieldOptions | 50007 | Default: false | | d_max | double | .google.protobuf.FieldOptions | 50001 | Default: inf | | d_min | double | .google.protobuf.FieldOptions | 50000 | Default: -inf | | legacy_field_id | uint64 | .google.protobuf.FieldOptions | 50010 | | | length | sint32 | .google.protobuf.FieldOptions | 50004 | Default: 2147483647 | | max_length | sint32 | .google.protobuf.FieldOptions | 50009 | Default: 2147483647 | | min_length | sint32 | .google.protobuf.FieldOptions | 50008 | Default: 0 | | optional | bool | .google.protobuf.FieldOptions | 50006 | Default: false | | regex | string | .google.protobuf.FieldOptions | 50005 | Default: .* | | ui_decimal_places | uint32 | .google.protobuf.FieldOptions | 50014 | Default: 0 | | ui_scale | double | .google.protobuf.FieldOptions | 50013 | Scaling of field value in user interfaces (UIs). Example: rad-to-degree conversions. Default: 1 | | ui_unit | string | .google.protobuf.FieldOptions | 50012 | Unit of field value in user interfaces (UIs). | | unit | string | .google.protobuf.FieldOptions | 50011 | Unit of field value | | e_desc | string | .google.protobuf.MessageOptions | 60000 | Error description Default: No additional error description available. | | generate | config.Generate | .google.protobuf.MessageOptions | 60003 | | | help | string | .google.protobuf.MessageOptions | 60001 | Help description | | secure | config.Secure | .google.protobuf.MessageOptions | 60002 | | | optional_one_of | bool | .google.protobuf.OneofOptions | 50006 | Default: false |

Top

blickfeld/config/advanced.proto

Advanced

Introduced in BSL v2.11 and firmware v1.11

Expert parameters: It is not recommended to adapt this calibrated configuration without understanding the influences on the resulting point cloud quality.

The current set of parameters is preliminary, additional parameters may be added or may get obsolete in the future.

Field Type Label Description
detector Advanced.Detector optional Refer to Detector
processing Advanced.Processing optional
Introduced in BSL v2.12 and firmware v1.12
Refer to Processing
server Advanced.Server optional
Introduced in BSL v2.13 and firmware v1.13
Refer to Server
time_synchronization Advanced.TimeSynchronization optional
Introduced in BSL v2.18 and firmware v1.19
Refer to TimeSynchronization

Advanced.Detector

The behavior of the detector can be adjusted to improve the performance under extreme environmental conditions, e.g. static setup with strong daylight or basement rooms without daylight.

Field Type Label Description
sensitivity float optional Relatively influences the sensitivity of the detector. Higher values might also result into range loss. It is recommended to validate the noise filter parameters after changes to this setting. Default: 1

Advanced.Processing

Introduced in BSL v2.12 and firmware v1.12

Processing parameters are set at the factory after calibration. Changing these values invalidates the factory calibration.

Field Type Label Description
range_offset float optional in [m] Default: 0
imu_static_rotation_offset float repeated
Introduced in BSL v2.19 and firmware v1.20
in [rad] - Offset rotation matrix for acceleration of IMU. Can be used to calibrate the accelerometer e.g. on a flat surface.
horizontal_phase_offset float optional
Introduced in BSL v2.19.5 and firmware v1.21.1
in [s] - Correction for phase offset in the horizontal field of view. This parameter might be adjusted in the field if the upper and lower half of the frame drifted horizontally. Default: 0

Advanced.Server

Introduced in BSL v2.13 and firmware v1.13

Parameters, which control the server behavior.

Field Type Label Description
default_point_cloud_subscription blickfeld.protocol.stream.Subscribe.PointCloud optional Overwrite default point cloud subscription. Can still be overridden with client requests.

Advanced.TimeSynchronization

Introduced in BSL v2.18 and firmware v1.19

Activate or deactivate synchronization and change parameters

Field Type Label Description
ntp Advanced.TimeSynchronization.NTP optional If this field is set, NTP synchronization is activated, which is the default configuration. Refer to NTP
ptp Advanced.TimeSynchronization.PTP optional If this field is set, PTP synchronization is activated and NTP synchronization is deactivated. Refer to PTP

Advanced.TimeSynchronization.NTP

The Blickfeld devices can use an NTPv4 client to synchronize the local device time to a time server. NTP can achieve synchronization accuracy below one millisecond for measurement results in local networks.

Field Type Label Description
servers string repeated Specify list of NTP server. By default, debian pool NTP servers are used.

Advanced.TimeSynchronization.PTP

The Blickfeld devices can use a PTP client to synchronize the local device time to a time server. PTP can achieve an higher accuracy than NTP in local networks.

Field Type Label Description
domain uint32 optional PTP domain number. Default: 0
delay_mechanism Advanced.TimeSynchronization.PTP.DelayMechanism optional Delay detection mode used Default: E2E
unicast_destinations string repeated Specify unicast slave addresses for unicast master operation, or unicast master addresses for slave operation. If this is set unicast mode will be activated.

Advanced.TimeSynchronization.PTP.DelayMechanism

Name Number Description
E2E 1 End to end delay detection
P2P 2 Peer to peer delay detection

Top

blickfeld/config/algorithm.proto

Algorithm

Introduced in BSL v2.17 and firmware v1.18

This section describes configuration of on-device algorithms.

Field Type Label Description
background_subtraction Algorithm.BackgroundSubtraction optional Refer to BackgroundSubtraction
neighbor_filter Algorithm.NeighborFilter optional Refer to NeighborFilter
static_transformation Algorithm.StaticTransformation optional Refer to StaticTransformation

Algorithm.BackgroundSubtraction

Introduced in firmware v1.16

This message configures the background subtraction.

The algorithm uses a configurable number of reference frames to estimate static points (background) in the scene. Once the number of reference frames are processed, it removes all static points from the point cloud output. The resulting point cloud then only contains the non-static points (foreground). Points that are a initially part of the foreground and but then stop moving, will be added to the background and thus disappear after a certain amount of time, which is given by the exponential decay rate parameter. Conversely, if an object that is already part of the background suddenly starts moving, it will be added to the foreground.

Field Type Label Description
initialization_frames uint32 optional Number of frames to initialize the background with Default: 10
exponential_decay_rate float optional Controls how fast objects switch between foreground and background. Exponential decay factor. Default: 0.0025

Algorithm.NeighborFilter

Introduced in firmware v1.18

The neighbor filter is a simple noise filter, which uses neighboring returns in the scan pattern to decide if returns should be filtered.

The algorithm iterates through all returns and removes all, which have zero neighbors. A neighbor return must be:

  • directly to the left / to the right / above / below the current return in the scan pattern

  • close to the current return. The maximum range, used for this condition, is defined by the angle spacing of the scan pattern and the range of the current return. As with higher distance, neighboring returns are expected to be further away.

No parameters can be configured at the moment.

Algorithm.StaticTransformation

Introduced in firmware v1.18

This message configures a static geometric transformation.

The algorithm applies a static rotation and translation to the point cloud output.

The rotation matrix R is expected to be a 3 x 3 matrix serialized in row major order.

Rotation in matrix representation:

R
r1,1 r1,2 r1,3
r2,1 r2,2 r2,3
r3,1 r3,2 r3,3

Rotation in serialized representation:

R = [r1,1, r1,2, … r3,2, r3,3]

The translation vector T is expected to be a 3 x 1 vector.

Translation in vector representation:

T
t1
t2
t3

Translation in serialized representation:

T = [t1, t2, t3] = [x, y, z]

Field Type Label Description
rotation_matrix float repeated rotation matrix R in serialized representation.
translation_vector float repeated translation vector T in serialized representation.

Top

blickfeld/config/generate.proto

Generate

Field Type Label Description
targets Generate.Targets repeated Internal generate targets

Generate.Targets

Internal use only

Name Number Description
DEFAULT 0
PROTO_HASH 1
MATLAB_BUS 2
CSTRUCT 3

Top

blickfeld/config/named_scan_pattern.proto

NamedScanPattern

Introduced in BSL v2.15 and firmware v1.16

Named scan patterns are saved on the device. There are two kinds of named scan patterns:

  1. Default scan patterns: Each device has default scan patterns, these are saved on the device with the firmware. They are not changeable.

  2. Custom scan patterns: Users can save scan patterns on the device for later use. If the scan pattern is saved as a named scan pattern, the time changing to this scan pattern will greatly decrease.

Field Type Label Description
name string optional The name has to be different of the default scan patterns and can only contain letters, numbers, space, underscore and minus.
config ScanPattern optional Scan pattern config, refer to ScanPattern
read_only bool optional this is an read_only flag and it will be set if this is a default scan pattern, which can't be changed or deleted. Default: false

Top

blickfeld/config/product.proto

Product

Product variant

Name Number Description
PRODUCT_CUBE 0
PRODUCT_CUBE_RANGE 2

Top

blickfeld/config/scan_pattern.proto

ScanPattern

The scan pattern defines the movement of the mirrors. The key parameters of the pattern are the horizontal and vertical fields of view (FoV) as well as the number of scan lines per frame. The frame rate is defined by the total number of scan lines and the oscillation frequency of the mirrors which is fixed and device-spcific.

For a more detailed explanation, see: Scan Pattern documentation

Field Type Label Description
horizontal ScanPattern.Horizontal optional Refer to ScanPattern.Horizontal
vertical ScanPattern.Vertical optional Refer to ScanPattern.Vertical
pulse ScanPattern.Pulse optional Refer to ScanPattern.Pulse
frame_rate ScanPattern.FrameRate optional Refer to ScanPattern.FrameRate
filter ScanPattern.Filter optional
Introduced in BSL v2.11 and firmware v1.11
Refer to Filter
constraints blickfeld.protocol.Constraint repeated

ScanPattern.Filter

Introduced in BSL v2.10 and firmware v1.9

Filter points and returns by point attributes during the post-processing on the device. This can be used to e.g. filter points with low intensity or to enable secondary returns.

Field Type Label Description
max_number_of_returns_per_point uint32 optional Set maximum number of returns per point. By default, secondary returns are disabled. Set this, e.g. to 2, to enable secondary returns. Default: 1
intensity blickfeld.protocol.OptionalValueRange optional Filter all points, which intensity values are not within this value range.
ambient_light_level blickfeld.protocol.OptionalValueRange optional Filter all points, which ambient light level values are not within this value range.
range blickfeld.protocol.OptionalValueRange optional Filter all points, which range values are not within this value range.
noise ScanPattern.Filter.Noise optional
Introduced in BSL v2.11 and firmware v1.11
Refer to Filter.Noise
delete_points_without_returns bool optional
Introduced in BSL v2.16 and firmware v1.17
All points without any returns are filtered if this setting is true. With active algorithms, such as background subtraction, this can reduce the bandwidth significantly.
Note: It is recommended to not estimate required network bandwidths when this setting is active. In scenarios, where from one frame to another, all points have returns (e.g. due to environmental changes), the peak bandwidths might increase significantly. This could result, in these scenarios, in frame losses. Default: false

ScanPattern.Filter.Noise

Introduced in BSL v2.11 and firmware v1.11

This is a preliminary interface to control the noise filter on the device. All points, which have a lower intensity than the minimum intensity calculated by this filter will be filtered out.

Changed in firmware v1.15. Please re-adjust filter configurations in scan patterns.

The internal algorithm implements a non-linear function, which describes the noise level for different ambient light levels. The function can be scaled with the gain and shifted with the offset.

Before firmware v1.15

The formula is: minimum_intensity = offset + gain * point.ambient_light_level, where the point.ambient_light_level is the ambient light level of the point the laser shoots at.

Field Type Label Description
offset uint32 optional Can be seen as minimum intensity filter, if there is no ambient light.
gain float optional The gain scales a non-linear function, which uses the ambient light level of the point the laser shoots at, as an input.
enable bool optional
Introduced in BSL v2.17 and firmware v1.18
This flag can be used to disable the internal noise filter completely. By default, the noise filter is enabled. Default: true

ScanPattern.FrameRate

This section defines the target frame rate for synchronization between several LiDAR devices. The feature is described in the Time synchronization documentation.

Field Type Label Description
target double optional Target frame rate during synchronization between several LiDAR devices
maximum double optional Read-only parameter for maximum achievable frame rate.
reference_time_offset double optional In [s]. Adds a constant value to the Unix reference time, starting from 00:00:00 UTC on January 1, 1970. It can be used to compensate delays or to interleave LiDAR devices. Default: 0 Default: 0

ScanPattern.Horizontal

This section defines the movement of the horizontal mirror. The mirror moves continuously with its own frequency. Each half-oscillation period of the mirror results in one scan line.

Field Type Label Description
fov float optional Unit: [rad] – optical field of view of the horizontal mirror. Note: In v2.2* and below, this was defined as a mechanical FoV.

ScanPattern.Pulse

This section defines the pattern in which the laser pulses and captures sample points

Field Type Label Description
angle_spacing float optional Unit: [rad] – This defines the angle within which the horizontal mirror moves between two laser pulses. This parameter therefore defines the horizontal sampling resolution.
type ScanPattern.Pulse.Type optional Refer to ScanPattern.Pulse.Type Default: INTERLEAVE
frame_mode ScanPattern.Pulse.FrameMode optional Refer to ScanPattern.Pulse.FrameMode Default: COMBINE_UP_DOWN
distortion_correction bool optional This parameter defines whether the distortion correction is applied when calculating the laser pulse angles. Default: True Default: true
custom ScanPattern.Pulse.Custom optional
Introduced in BSL v2.15 and firmware v1.16
Refer to ScanPattern.Pulse.Custom

ScanPattern.Pulse.Custom

Introduced in BSL v2.15 and firmware v1.16

Custom scan pattern configuration. Required for different use cases, as e.g. angle triggers, point triggers, or detector recordings.

Field Type Label Description
angle_trigger ScanPattern.Pulse.Custom.AngleTrigger optional
point_trigger ScanPattern.Pulse.Custom.PointTrigger optional
duration ScanPattern.Pulse.Custom.Duration optional

ScanPattern.Pulse.Custom.AngleTrigger

Allows to trigger based on horizontal angles.

Field Type Label Description
angles ScanPattern.Pulse.Custom.AngleTrigger.Angle repeated List of angles

ScanPattern.Pulse.Custom.AngleTrigger.Angle

Field Type Label Description
horizontal_angle float optional in [rad]
scanline_id uint64 optional Define in which scanline the trigger should occur, if none is given, it will trigger in all scanlines
enabled_triggers ScanPattern.Pulse.Custom.Trigger repeated

ScanPattern.Pulse.Custom.Duration

Specify duration for trigger type in seconds.

Field Type Label Description
external_0 float optional in [s] Default: 0.0001
external_1 float optional in [s] Default: 0.0001

ScanPattern.Pulse.Custom.PointTrigger

Set point triggers for the normal equi-distant horizontal scan pattern.

Field Type Label Description
points ScanPattern.Pulse.Custom.PointTrigger.Point repeated

ScanPattern.Pulse.Custom.PointTrigger.Point

Field Type Label Description
id uint64 optional Define which point ID should be triggered
enabled_triggers ScanPattern.Pulse.Custom.Trigger repeated

ScanPattern.Vertical

This section defines the movement of the vertical mirror within one frame. The mirror moves for from 0 degrees to the configured target FoV (up-ramping phase) and back to 0 degrees (down-ramping phase) with its eigenfrequency. The number of scanlines for each phase can be configured. Due to the dynamics of the mirror, a certain number of scan lines are required to reach the target FoV and then to reach 0 degrees again. Consequently, if the limit is reached, a lower number of scan lines requires a reduced FoV. Thus, a higher number of scan lines allows a larger vertical FoV. The vertical FoV is limited by the optical components.

Note: Due to the time required for one scan line, the rounded even number of scan lines directly scales inverse proportionally with65t the frame rate.

For a more detailed explanation, see: Scan Pattern documentation

Field Type Label Description
fov float optional Unit: [rad] – FoV in the center of the frame. Due to the eye shape of the scan pattern, the vertical FoV decreases the outer boundaries of the horizontal mirror.
scanlines_up uint32 optional Configures the number of scan lines required for the up-ramping phase. During the up-ramping phase, the vertical mirror increases its amplitude from 0 degrees to the target FoV. Default: 200 Default: 40
scanlines_down uint32 optional Configures the amount of scan lines required for the down-ramping phase. During the down-ramping phase, the vertical mirror decreases its amplitude from the target FoV to 0 degrees. Default: 30 Default: 40

ScanPattern.Pulse.Custom.Trigger

List of available device triggers.

Name Number Description
TRG_EXTERNAL_0 1 External output pin, routed to TEST0 on the debug board.
TRG_EXTERNAL_1 2 External output pin, routed to TEST1 on the debug board.
TRG_DETECTOR 3 Internal detector recording, which can retrieved with the detector stream.
TRG_LASER 4 Trigger laser.

ScanPattern.Pulse.FrameMode

Because of the mirrors oscillating and the resulting Lissajous curve, it is not possible to pulse in a completely arbitrary pattern. A frame always starts with a phase in which the vertical mirror increases its amplitude (up-ramping). It is followed by a second phase, in which it decreases its amplitude until it no longer moves (down-ramping). It is possible to pulse in both phases. There are four different options to pulse:

Name Number Description
NONE 0
COMBINE_UP_DOWN 1 The device pulses in the up-ramping and down-ramping phases and one frame is created by combining the resulting sample points.
ONLY_UP 2 The device pulses in the up-ramping phase and does not pulse in the down-ramping phase.
ONLY_DOWN 3 The device is does not pulse in the up-ramping phase and pulses in the down-ramping phase.
SEPARATE 4 The device pulses in the up-ramping and down-ramping phases and one frame for each phase is created.

ScanPattern.Pulse.Type

The device pulses depending on the mirror positioning. Currently, only pulse triggering on the horizontal angle is supported. The laser pulses are emittet with the configured angular spacing.

Name Number Description
EQUI_HORIZONTAL_ANGLE 0 The laser is triggered depending on the horizontal angle of the laser beam with the configured angle spacing.
EQUI_DENSITY 1 Reserved for future use. Not yet supported.
CUSTOM 2 Internal feature for custom scan patterns
INTERLEAVE 3 The laser is triggered depending on the horizontal angle of the laser beam with the configured angle spacing. Scanlines are shifted by angle_spacing/4 with alternate directions. This doubles the horizontal density with the COMBINE_UP_DOWN FrameMode and efficiently uses the down-ramp phase in the inner horizontal FoV.

Top

blickfeld/config/secure.proto

Secure

Field Type Label Description
permissions Secure.Permissions repeated
cert_type Secure.CertType optional
version_major uint32 optional
version_minor uint32 optional
version_patch uint32 optional

Secure.CertType

Name Number Description
CLIENT 0
CUBE 1

Secure.Permissions

do NOT change enum labels, they are used as strings in ssl certs

Name Number Description
PUBLIC 0
DEVELOPER 1

Top

blickfeld/data/algorithm.proto

Algorithm

Introduced in BSL v2.17 and firmware v1.18

This section describes the additional data output of on-device algorithms. The data is attached to the frame.

Field Type Label Description
background_subtraction Algorithm.BackgroundSubtraction optional Refer to BackgroundSubtraction.
neighbor_filter Algorithm.NeighborFilter optional Refer to NeighborFilter.
static_transformation Algorithm.StaticTransformation optional Refer to StaticTransformation.
execution_time float optional Execution time of the algorithm in [s]

Algorithm.BackgroundSubtraction

The description of the algorithm can be found at config.Algorithm.BackgroundSubtraction.

The algorithm does not output any additional information. It subtracts returns from the main frame.

Algorithm.NeighborFilter

The description of the algorithm can be found at config.Algorithm.NeighborFilter.

The algorithm does not output any additional information. It subtracts returns from the main frame.

Algorithm.StaticTransformation

The description of the algorithm can be found at config.Algorithm.StaticTransformation.

The algorithm does not output any additional information. It transforms the cartesian coordinates in the frame.

Top

blickfeld/data/frame.proto

Frame

This section describes the contents of a point cloud frame.

Field Type Label Description
id uint64 optional Incremental frame ID since startup of the device
start_time_ns uint64 optional Unit: [s] – start frame timestamp
scan_pattern blickfeld.protocol.config.ScanPattern optional Refer to ScanPattern
is_ramp_up_phase bool optional
Introduced in BSL v2.16 and firmware v1.17
If the frame_mode in the scan pattern is set to SEPARATE, this value indicates if the given frame was captured during up-ramping or down-ramping.
total_number_of_points uint32 optional Number of laser pulses emitted in this frame.
total_number_of_returns uint32 optional Number of returned points recorded: Each point of the total_number_of_points can produce several returns.
scanlines Scanline repeated Refer to Scanline
packed Frame.Packed optional
Introduced in BSL v2.16 and firmware v1.17
Refer to Packed
algorithms Algorithm repeated
Introduced in BSL v2.17 and firmware v1.16
Refer to data.Algorithm. Each algorithm configured can output additional data, which is provided with this field.

Frame.Packed

Introduced in BSL v2.16 and firmware v1.17

This format returns point clouds as flat binary structures. These can be efficiently encoded & decoded, which increases the performance on low-performance clients significantly. The network bandwidth is usually slightly higher as the data is not encoded.

Note: The reference frame concept is handled differently for packed structures. To activate the packed format, it is sufficient to set an empty packed message in the reference frame. The requested fields need to be selected in the scanlines structure. Refer to REF_FRAME_PACKED in the client implementations.

Field Type Label Description
length uint32 optional Length of arrays
cartesian bytes optional Cartesian coordinates. 3-dimensional array in row-major format with [x, y, z] tuples. Unit: [m]. Type: Float32. Byte Order: Big Endian.
direction bytes optional Polar coordinates. 2-dimensional array in row-major format with [azimuth, elevation] tuples. Unit: [rad]. Type: Float32. Byte Order: Big Endian.
range bytes optional Distance to the return. 1-dimensional array. Unit: [m]. Type: Float32. Byte Order: Big Endian.
intensity bytes optional Intensity of the returned laser pulse. 1-dimensional array. Type: UInt32. Byte Order: Big Endian.
ambient_light_level bytes optional Ambient light level in the direction of the point. 1-dimensional array. Type: UInt32. Byte Order: Big Endian.
start_offset_ns bytes optional Starting time of the point in relation to Frame.start_time_ns. 1-dimensional array. Unit: [ns]. Type: UInt64. Byte Order: Big Endian.
point_id bytes optional Unique point identifier within a frame and scan pattern. 1-dimensional array. Type: UInt32. Byte Order: Big Endian.
channel_id bytes optional Identifier of the channel that detected the point. 1-dimensional array. Type: UInt8.
return_id bytes optional Identifier of the return. Note: Returns are ordered by intensity not by distance. 1-dimensional array. Type: UInt8.

Top

blickfeld/data/imu.proto

IMU

Introduced in BSL v2.18 and firmware v1.19

The Cube has an on-board IMU, which can be used for e.g. mapping applications or static auto-leveling.

Field Type Label Description
start_time_ns uint64 optional Unit: [ns] – start timestamp of data. The start_offset_ns in each sample refers to this value. The timestamp is synchronized to the ones in point cloud frames.
samples IMU.Sample repeated Refer to Sample
packed IMU.Packed optional Refer to Packed

IMU.Packed

Field Type Label Description
length uint32 optional Length of arrays
start_offset_ns bytes optional Starting time of the point in relation to Data.start_time_ns. 1-dimensional array. Unit: [ns]. Type: UInt64. Byte Order: Big Endian.
acceleration bytes optional Accerlation. 3-dimensional array in row-major format with [x, y, z] tuples. Unit: [g]. Type: Float32. Byte Order: Big Endian.
angular_velocity bytes optional Angular velocity, measured with gyroscope. 3-dimensional array in row-major format with [x, y, z] tuples. Unit: [rad/s]. Type: Float32. Byte Order: Big Endian.

IMU.Sample

Describes a single IMU state. Data rate is approx. 1.125 khz.

Field Type Label Description
start_offset_ns uint64 optional Unit: [ns] – Offset to start_time_ns
acceleration float repeated Unit: [g] - Format: [x,y,z] - Measured acceleration for 3-axes.
angular_velocity float repeated Unit: [rad/s] - Format: [x,y,z] - Measured angular velocity by gyroscope for 3-axes.

Top

blickfeld/data/point.proto

Point

This section describes the contents of a single point of a point cloud frame or scan line. Each point resembles a direction in which the laser has fired. From each point (direction) the device can receive several responses/returns, see Point.Return.

Field Type Label Description
id uint32 optional Point ID in the corresponding frame
returns Point.Return repeated Refer to Point.Return
start_offset_ns uint64 optional Unit: [ns] - starting time of the point in relation to Frame.start_time_ns
ambient_light_level uint32 optional Ambient light level in the direction of the point
direction Point.Direction optional Refer to Point.Direction
channel_id uint32 optional ID of the channel that detected the point
error_flags Point.ErrorFlag repeated Refer to Point.ErrorFlag

Point.Direction

This section describes the direction and the origin of a point. Use these polar coordinates combined with the range information of a given return, if you want to locate the reflection in the spherical coordinatesystem.

Field Type Label Description
azimuth float optional Unit: [rad] - azimuth angle: Angle with respect to y-z plane
elevation float optional Unit: [rad] - elevation angle: Angle with respect to x-y plane
origin float repeated Unit: [m] - origin of the laser beam [x,y,z]

Point.Return

This section describes the contents of a single return of a point, sorted by intensity. A return is created when the LiDAR detects the laser light of the reflection of an object.

Field Type Label Description
id uint32 optional ID of the return in the point
cartesian float repeated Unit: [m] – Cartesian coordinates of the target [x,y,z]
range float optional Unit: [m] – distance of target to the origin
intensity uint32 optional Intensity of the returned laser pulse

Point.ErrorFlag

Error flag indicating why a point delivers no valid returns. If a flag is set, the point should not be interpreted neither processed. Flags are only set temporarily for a short period of time. If the error state does not recover, the device will stop operation.

Name Number Description
E_VIBRATION_THRESHOLD_EXCEEDED 1 The environmental vibration threshold was exceeded. This should not happen in normal operation.

Top

blickfeld/data/point_cloud.proto

PointCloud

A point cloud object can contain either a full frame or a single scan line.

Field Type Label Description
header PointCloud.Header optional Refer to PointCloud.Header
frame Frame optional Refer to Frame
scanline Scanline optional Refer to Scanline

PointCloud.Header

This section describes the contents of a point cloud header.

Field Type Label Description
legacy_cube_serial_number string optional Legacy serial number of the device which recorded the pointcloud
cube_serial_number string optional Serial number of the device which recorded the pointcloud
start_time_ns uint64 optional Unit: [s] - Start timestamp of the requested pointcloud stream
firmware_version string optional Firmware version of the device which recorded the pointcloud
hardware_variant blickfeld.protocol.update.HardwareVariant optional Hardware variant of the device which recorded the pointcloud
subscription blickfeld.protocol.stream.Subscribe.PointCloud optional
Introduced in BSL v2.16 and firmware v1.17
Used & merged subscription for stream

Top

blickfeld/data/scanline.proto

Scanline

This section describes the contents of a single scan line in a point cloud frame.

Field Type Label Description
id uint64 optional Scan line ID in the corresponding frame
frame_id uint64 optional Frame ID of the corresponding frame
points Point repeated Refer to Point
start_offset_ns uint64 optional Unit: [ns] - start time of the scanline in relation to Frame.start_time_ns

Top

blickfeld/file/general.proto

Client

Field Type Label Description
library_version string optional Library version
file_time_ns uint64 optional Unit: [ns] - File time stamp
language blickfeld.protocol.Language optional Used library language for file creation

Top

blickfeld/file/point_cloud.proto

PointCloud

This section describes the contents of a point cloud. The first message in a Blickfeld protobuf pointcloud should always be the PointCloud.Header message followed by PointCloud.Data messages.

PointCloud.Data

Field Type Label Description
frame blickfeld.protocol.data.Frame optional Refer to PointCloud
footer PointCloud.Footer optional

PointCloud.Header

Field Type Label Description
device blickfeld.protocol.data.PointCloud.Header optional Refer to PointCloud.Header
client Client optional

PointCloud.Metadata

Field Type Label Description
header PointCloud.Header optional
footer PointCloud.Footer optional

Top

blickfeld/status/imu.proto

IMU

Introduced in BSL v2.18 and firmware v1.19

This section defines the status of the IMU.

Field Type Label Description
static_state IMU.StaticState optional

IMU.StaticState

Field Type Label Description
acceleration float repeated

Top

blickfeld/status/main.proto

Status

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

Field Type Label Description
scanner status.Scanner optional Refer to Scanner
temperatures status.Temperature repeated Refer to Temperature
server status.Server optional Refer to Client
imu status.IMU optional
Introduced in BSL v2.18 and firmware v1.19
Refer to IMU
time_synchronization status.TimeSynchronization optional
Introduced in BSL v2.18 and firmware v1.19
Refer to TimeSynchronization

Top

blickfeld/status/scanner.proto

Scanner

This section defines the status of the device.

Field Type Label Description
state Scanner.State optional Refer to Scanner.State
scan_pattern blickfeld.protocol.config.ScanPattern optional Refer to ScanPattern
error blickfeld.protocol.Error optional Refer to Error

Scanner.State

Name Number Description
INITIALIZING 1 Device is initializing the hardware.
READY 2 Device is ready to start and no error occurred.
STARTING 3 Device is starting a point cloud recording, but is not yet recording.
RUNNING 4 Device is recording a point cloud.
STOPPING 5 Device stops point cloud recording; it is no longer recording.
ERRORED 6 Device is in an error state; it can no longer operate.
SELF_TESTING 7 Device is testing the hardware.

Top

blickfeld/status/server.proto

Server

This section defines the status of the network server.

Field Type Label Description
clients Server.Client repeated
network_stats Server.NetworkStats optional

Server.Client

Field Type Label Description
subscriptions blickfeld.protocol.stream.Subscribe repeated
network_stats Server.NetworkStats optional
identifier string optional

Server.NetworkStats

Field Type Label Description
sent Server.NetworkStats.Channel optional
received Server.NetworkStats.Channel optional
dropped_messages uint64 optional Default: 0

Server.NetworkStats.Channel

Field Type Label Description
total_byte_count uint64 optional Default: 0
bytes_per_second float optional
maximum_bytes_per_second float optional

Top

blickfeld/status/temperature.proto

Temperature

This section describes the temperature of the hardware modules in the device.

Field Type Label Description
sensor Temperature.Sensor optional Refer to Temperature.Sensor
value float optional Unit: [degrees Celsius] – temperature value of the module.
failed_reason string optional Error reason why the temperature cannot be read out.

Temperature.Sensor

This section describes the hardware modules in the device.

Name Number Description
UNKNOWN 0
LDM 1 Laser and detector module
ETHERNET 2 Ethernet adapter
MSB 3 Mixed signal board
PL 4 Programmable logic
PS 5 Processing system
SCANNER_SMALL 6 Vertical mirror
SCANNER_BIG 7 Horizontal mirror

Top

blickfeld/status/time_synchronization.proto

TimeSynchronization

Introduced in BSL v2.18 and firmware v1.19

This section defines the synchronization status of the server.

Field Type Label Description
state TimeSynchronization.State optional
offset_from_master float optional Current offset value from master device in seconds. NTP: time offset (seconds) in loopstats PTP: It is the main output of the PTP engine that is in the worker state. This value is the input for clock corrections in the clock servo algorithms. This value is typically measured when estimating the performance of the worker device.
ntp TimeSynchronization.NTP optional Refer to NTP
ptp TimeSynchronization.PTP optional Refer to PTP

TimeSynchronization.NTP

Field Type Label Description
frequency_offset float optional frequency offset (parts per million - PPM) as in loopstats
rms_jitter float optional RMS jitter (seconds) as in loopstats
allan_deviation float optional Allan deviation (PPM) as in loopstats
clock_discipline_time_constant float optional clock discipline time constant as in loopstats

TimeSynchronization.PTP

Field Type Label Description
state string optional ONLY AVAILABLE FOR PTP, NTP doesnt have a state Follwing states can occur: init: Initializing, flt: Faulty, lstn_init: Listening (first time), lstn_reset: Listening (subsequent reset), pass: Passive (not best master, not announcing), uncl: Uncalibrated, slv: Worker, pmst: Pre-master, mst: Master (active), dsbl: Disabled, ? (unk): Unknown state
clock_id string optional TODO Find out for NTP!! Clock ID Port identity of the current best master, as defined by IEEE 1588 standard. This ID is the local clock's ID if the local clock is the best master. This parameter is displayed as clock_id or port (host). Port is the PTP clock port number, not the User Datagram Protocol (UDP) port numbers. The clock ID is an Extended Unique Identifier (EUI)-64 64-bit ID, converted from the 48-bit MAC address, by inserting 0xfffe at the middle of the MAC address.
one_way_delay float optional One-way delay Current value of one-way delay (or mean-path delay) in seconds, calculated by the ptpd daemon that is in the worker state from the delay request and delay response message exchange. Note: If this value remains at zero, it means that no delay response messages are being received, which might be because of a network issue.
slave_to_master float optional Slave to master Intermediate offset value (seconds) extracted from the delay request and delay response message exchange. This value is used for computing one-way delay. If the last value was rejected by a filter, the previous value is shown in the log file. This value is zero (0) if the delay response messages are not received.
master_to_slave float optional Master to slave Intermediate offset value (seconds) extracted from the sync messages. This value is used for computing the offset value from the master devices. If the last value was rejected by a filter, the previous value is shown in the log file.
observed_drift float optional Observed drift The frequency difference between the worker clock and the master clock as measured by the integral accumulator of the clock control proportional integral (PI) servo model. This value stabilizes when the clock offset value is stabilized, and this value is used to detect clock stability.
last_packet_received string optional Last packet Received This field shows which message was received last. It displays S for sync messages and D for delay response messages. If a worker device logs no D entries, it means that the worker device is not receiving delay response messages because of network issue.

TimeSynchronization.State

Name Number Description
STOPPED 1
INITIALIZING 2
SYNCED 3
FAILED 4

Top

blickfeld/stream/connection.proto

Subscribe

This section describes the different streams to which it is possible to subscribe. A stream regularly provides data or status updates for the user. The events will not be pushed automatically to the BSL; the client has to retrieve them.

Field Type Label Description
point_cloud Subscribe.PointCloud optional Refer to Subscribe.PointCloud
status Subscribe.Status optional Refer to Subscribe.Status
developer Subscribe.Developer optional Refer to Subscribe.Developer
raw_file Subscribe.RawFile optional Refer to Subscribe.RawFile
imu Subscribe.IMU optional
Introduced in BSL v2.18 and firmware v1.19
Refer to Subscribe.IMU

Subscribe.Developer

Internal use only

Subscribe.IMU

Introduced in BSL v2.18 and firmware v1.19

The Cube has an on-board IMU, which can be used for e.g. mapping applications or static auto-leveling. A stream can be requested with this subscription. The default rate is approx. 1.125 kHz and is provided in bursts. The timestamps inside the protocol are synchronized to the ones in point cloud frames.

Field Type Label Description
packed_format bool optional Request a packed binary format. This is currently used for efficent Python numpy decoding. Default: false

Subscribe.PointCloud

This request is used for subscribing to a point cloud stream.

Field Type Label Description
reference_frame blickfeld.protocol.data.Frame optional
Introduced in BSL v2.10 and firmware v1.9
If present, only fields that are set in this message and submessages will be present in the point cloud. If less fields are requested, the Protobuf encoding and network transport time can reduce significantly.
filter blickfeld.protocol.config.ScanPattern.Filter optional
Introduced in BSL v2.10 and firmware v1.9
Refer to ScanPattern.Filter. Overrides parameters of scan pattern.
algorithms blickfeld.protocol.config.Algorithm repeated
Introduced in BSL v2.17 and firmware v1.16
Refer to config.Algorithm. Sets algorithms, which are initialized, configured for the stream and are executed on each frame in the post-processing on the device.
prepend_advanced_config_algorithms bool optional
Introduced in BSL v2.17 and firmware v1.16
With the server.default_point_cloud_subscription algorithms can be persisted on the device and they are by default prepended to the list of sent algorithms in the subscribe request. This behaviour can be disabled with this field to e.g. disable or overwrite all algorithms. Default: true

Subscribe.RawFile

Introduced in BSL v2.13 and firmware v1.13

This request is used for subscribing to a raw file stream. The requested stream is directly packed in the Blickfeld data format and only raw bytes are sent to the client, which it should write sequentially in a file. An Unsubscribe request with the same request data must be sent to properly end the file stream. The request raw file stream is ended with an EndOfStream event.

Field Type Label Description
point_cloud Subscribe.PointCloud optional Subscribe to a raw point cloud stream. Refer to Subscribe.PointCloud.

Subscribe.Status

This request is used for subscribing to a status stream.

Top

blickfeld/stream/event.proto

Event

This section describes the events of streams.

Field Type Label Description
point_cloud blickfeld.protocol.data.PointCloud optional Refer to PointCloud
status blickfeld.protocol.Status optional Refer to Status
developer Event.Developer optional Refer to Event.Developer
raw_file bytes optional
Introduced in BSL v2.13 and firmware v1.13
Raw bytes, which should be written sequentially in a file. Refer to RawFile.
end_of_stream Event.EndOfStream optional
Introduced in BSL v2.13 and firmware v1.13
Refer to EndOfStream
imu blickfeld.protocol.data.IMU optional
Introduced in BSL v2.18 and firmware v1.19
Refer to IMU

Event.Developer

Internal use only

Event.EndOfStream

Introduced in BSL v2.13 and firmware v1.13

Event to indicate the end of stream. This is called after an Unsubscribe request. No further events will arrive for the subscribed stream after this event.

Field Type Label Description
subscription Subscribe optional Ended subscription. Refer to Subscribe.

Top

blickfeld/update/hardware.proto

partial_module_eeprom_msg

partial parse of {ldm,scanner,msb}_eeprom_msg

Field Type Label Description
hardware_version string optional

partial_trenz_eeprom_msg

partial parse of trenz_eeprom_msg

Field Type Label Description
hardware_variant HardwareVariant optional

HardwareVariant

do NOT change enum labels, they are used as strings in code

Name Number Description
ALL_HARDWARE 5
UNKNOWN_HARDWARE 6
NO_HARDWARE 7
CUBE_V0_2 0
CUBE_V0_3 1
CUBE_V1_0 4
AURORA_P3 3
APOLLON_A0 2
APOLLON_A1_BDU 8

Top

blickfeld/update/manifest.proto

manifest_msg

Field Type Label Description
min_bus_version string optional
image_type manifest_msg.ImageType optional
compatible_hardware manifest_msg.CompatibleHardware optional
secure bool optional Default: false

manifest_msg.CompatibleHardware

Field Type Label Description
variant HardwareVariant repeated
msb string repeated
scanner_big string repeated
scanner_small string repeated
hsd string repeated

manifest_msg.ImageType

Name Number Description
PARTITIONED 0
SYSTEM 1

Scalar Value Types

.proto Type Notes C++ Type Python Type
double double float
float float float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 int/long
uint32 Uses variable-length encoding. uint32 int/long
uint64 Uses variable-length encoding. uint64 int/long
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 int/long
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 int/long
sfixed32 Always four bytes. int32 int
sfixed64 Always eight bytes. int64 int/long
bool bool boolean
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string str/unicode
bytes May contain any arbitrary sequence of bytes. string str