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

OptionalValueRange

Field Type Label Description
minimum float optional
maximum float optional

ValueRange

Field Type Label Description
minimum float optional
maximum float optional

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

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

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

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.

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.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 | | i_max | uint64 | .google.protobuf.FieldOptions | 50003 | Default: 18446744073709551615 | | i_min | sint64 | .google.protobuf.FieldOptions | 50002 | Default: -9223372036854775808 | | 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

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

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.

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

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.

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/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
scanlines Scanline repeated Refer to Scanline
start_time_ns uint64 optional Unit: [s] – start frame timestamp
scan_pattern blickfeld.protocol.config.ScanPattern optional Refer to ScanPattern
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. |

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

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 Client.Language optional Used library language for file creation

Client.Language

Name Number Description
CPP 1
PYTHON 2
TYPESCRIPT 3

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

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

Subscribe.Developer

Internal use only

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.

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

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