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

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
legacy_scan_pattern blickfeld.protocol.config.ScanPattern optional Deprecated old ´scan_pattern´ definition

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_TEST 7 Device is testing the hardware.

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

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: EQUI_HORIZONTAL_ANGLE
frame_mode ScanPattern.Pulse.FrameMode optional Refer to ScanPattern.Pulse.FrameMode Default: ONLY_UP
distortion_correction bool optional This parameter defines whether the distortion correction is applied when calculating the laser pulse angles. Default: True Default: true

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: 200
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: 30

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.
EQUI_DENSITY 1 Reserved for future use. Not yet supported.

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/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/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/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/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
_asJSON string optional Internal use only
accept_format Format optional Internal use only Default: PROTOBUF

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
legacy_config config.ScanPattern optional Deprecated

Request.GetScanPattern

This request is used to retrieve the currently set ScanPattern.

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

This request is used for configuring a Scan Pattern.

Field Type Label Description
config config.ScanPattern optional Refer to ScanPattern
persist bool optional Persists with the scan pattern and sets it after a power cycle. Default: False Default: false
legacy_config config.ScanPattern optional Deprecated old 'config' due to horizontal field of view definition

Request.Status

This request is used for receiving the current Status.

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
_asJSON string optional Internal use only

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
legacy_config config.ScanPattern optional Deprecated

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
legacy_config config.ScanPattern optional Deprecated

Response.Hello

This response is sent out after establishing a connection.

Field Type Label Description
protocol_version uint32 optional

Response.SetScanPattern

This response is sent out after setting a scan pattern.

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/stream/connection.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

Event.Developer

Internal use only

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

Subscribe.Developer

Internal use only

Subscribe.PointCloud

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

Subscribe.Status

This request is used for subscribing to a status stream.

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

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

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