# 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
- [blickfeld/status/main.proto](#blickfeld/status/main.proto)
- [Status](#blickfeld.protocol.Status)
- [blickfeld/status/scanner.proto](#blickfeld/status/scanner.proto)
- [Scanner](#blickfeld.protocol.status.Scanner)
- [Scanner.State](#blickfeld.protocol.status.Scanner.State)
- [blickfeld/status/temperature.proto](#blickfeld/status/temperature.proto)
- [Temperature](#blickfeld.protocol.status.Temperature)
- [Temperature.Sensor](#blickfeld.protocol.status.Temperature.Sensor)
- [blickfeld/config/scan_pattern.proto](#blickfeld/config/scan_pattern.proto)
- [ScanPattern](#blickfeld.protocol.config.ScanPattern)
- [ScanPattern.FrameRate](#blickfeld.protocol.config.ScanPattern.FrameRate)
- [ScanPattern.Horizontal](#blickfeld.protocol.config.ScanPattern.Horizontal)
- [ScanPattern.Pulse](#blickfeld.protocol.config.ScanPattern.Pulse)
- [ScanPattern.Vertical](#blickfeld.protocol.config.ScanPattern.Vertical)
- [ScanPattern.Pulse.FrameMode](#blickfeld.protocol.config.ScanPattern.Pulse.FrameMode)
- [ScanPattern.Pulse.Type](#blickfeld.protocol.config.ScanPattern.Pulse.Type)
- [blickfeld/data/point_cloud.proto](#blickfeld/data/point_cloud.proto)
- [PointCloud](#blickfeld.protocol.data.PointCloud)
- [PointCloud.Header](#blickfeld.protocol.data.PointCloud.Header)
- [blickfeld/data/frame.proto](#blickfeld/data/frame.proto)
- [Frame](#blickfeld.protocol.data.Frame)
- [blickfeld/data/scanline.proto](#blickfeld/data/scanline.proto)
- [Scanline](#blickfeld.protocol.data.Scanline)
- [blickfeld/data/point.proto](#blickfeld/data/point.proto)
- [Point](#blickfeld.protocol.data.Point)
- [Point.Direction](#blickfeld.protocol.data.Point.Direction)
- [Point.Return](#blickfeld.protocol.data.Point.Return)
- [Point.ErrorFlag](#blickfeld.protocol.data.Point.ErrorFlag)
- [blickfeld/connection.proto](#blickfeld/connection.proto)
- [Request](#blickfeld.protocol.Request)
- [Request.Developer](#blickfeld.protocol.Request.Developer)
- [Request.FillScanPattern](#blickfeld.protocol.Request.FillScanPattern)
- [Request.GetScanPattern](#blickfeld.protocol.Request.GetScanPattern)
- [Request.Hello](#blickfeld.protocol.Request.Hello)
- [Request.SetScanPattern](#blickfeld.protocol.Request.SetScanPattern)
- [Request.Status](#blickfeld.protocol.Request.Status)
- [Response](#blickfeld.protocol.Response)
- [Response.Developer](#blickfeld.protocol.Response.Developer)
- [Response.FillScanPattern](#blickfeld.protocol.Response.FillScanPattern)
- [Response.GetScanPattern](#blickfeld.protocol.Response.GetScanPattern)
- [Response.Hello](#blickfeld.protocol.Response.Hello)
- [Response.SetScanPattern](#blickfeld.protocol.Response.SetScanPattern)
- [Format](#blickfeld.protocol.Format)
- [blickfeld/stream/connection.proto](#blickfeld/stream/connection.proto)
- [Event](#blickfeld.protocol.stream.Event)
- [Event.Developer](#blickfeld.protocol.stream.Event.Developer)
- [Subscribe](#blickfeld.protocol.stream.Subscribe)
- [Subscribe.Developer](#blickfeld.protocol.stream.Subscribe.Developer)
- [Subscribe.PointCloud](#blickfeld.protocol.stream.Subscribe.PointCloud)
- [Subscribe.Status](#blickfeld.protocol.stream.Subscribe.Status)
- [blickfeld/error.proto](#blickfeld/error.proto)
- [Error](#blickfeld.protocol.Error)
- [Error.ConnectionClosed](#blickfeld.protocol.Error.ConnectionClosed)
- [Error.Empty](#blickfeld.protocol.Error.Empty)
- [Error.HardwareError](#blickfeld.protocol.Error.HardwareError)
- [Error.InvalidRequest](#blickfeld.protocol.Error.InvalidRequest)
- [Error.NoDeviceDiscovered](#blickfeld.protocol.Error.NoDeviceDiscovered)
- [Error.NotAllowed](#blickfeld.protocol.Error.NotAllowed)
- [Error.NotFound](#blickfeld.protocol.Error.NotFound)
- [Error.NotImplemented](#blickfeld.protocol.Error.NotImplemented)
- [Error.NotInRange](#blickfeld.protocol.Error.NotInRange)
- [Error.OutdatedClientProtocol](#blickfeld.protocol.Error.OutdatedClientProtocol)
- [Error.OutdatedServerProtocol](#blickfeld.protocol.Error.OutdatedServerProtocol)
- [Error.ScannerBusy](#blickfeld.protocol.Error.ScannerBusy)
- [Error.ServerImplementation](#blickfeld.protocol.Error.ServerImplementation)
- [Error.SystemStop](#blickfeld.protocol.Error.SystemStop)
- [Error.TimeSyncFailed](#blickfeld.protocol.Error.TimeSyncFailed)
- [Error.Unknown](#blickfeld.protocol.Error.Unknown)
- [Error.UnknownErrorCode](#blickfeld.protocol.Error.UnknownErrorCode)
- [Error.WrongOperationMode](#blickfeld.protocol.Error.WrongOperationMode)
- [blickfeld/file/general.proto](#blickfeld/file/general.proto)
- [Client](#blickfeld.protocol.file.Client)
- [Client.Language](#blickfeld.protocol.file.Client.Language)
- [blickfeld/file/point_cloud.proto](#blickfeld/file/point_cloud.proto)
- [PointCloud](#blickfeld.protocol.file.PointCloud)
- [PointCloud.Data](#blickfeld.protocol.file.PointCloud.Data)
- [PointCloud.Footer](#blickfeld.protocol.file.PointCloud.Footer)
- [PointCloud.Footer.Event](#blickfeld.protocol.file.PointCloud.Footer.Event)
- [PointCloud.Footer.Stats](#blickfeld.protocol.file.PointCloud.Footer.Stats)
- [PointCloud.Footer.Stats.Counter](#blickfeld.protocol.file.PointCloud.Footer.Stats.Counter)
- [PointCloud.Header](#blickfeld.protocol.file.PointCloud.Header)
- [PointCloud.Metadata](#blickfeld.protocol.file.PointCloud.Metadata)
- [Scalar Value Types](#scalar-value-types)
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](#blickfeld.protocol.status.Scanner) | optional | Refer to [Scanner](#blickfeld.protocol.status.scanner.Scanner) |
| temperatures | [status.Temperature](#blickfeld.protocol.status.Temperature) | repeated | Refer to [Temperature](#blickfeld.protocol.status.temperature.Temperature) |
Top
## blickfeld/status/scanner.proto
### Scanner
This section defines the status of the device.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| state | [Scanner.State](#blickfeld.protocol.status.Scanner.State) | optional | Refer to [Scanner.State](#blickfeld.protocol.status.Scanner.State) |
| scan_pattern | [blickfeld.protocol.config.ScanPattern](#blickfeld.protocol.config.ScanPattern) | optional | Refer to [ScanPattern](#blickfeld.protocol.config.ScanPattern) |
| error | [blickfeld.protocol.Error](#blickfeld.protocol.Error) | optional | Refer to [Error](#blickfeld.protocol.Error) |
| legacy_scan_pattern | [blickfeld.protocol.config.ScanPattern](#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](#blickfeld.protocol.status.Temperature.Sensor) | optional | Refer to [Temperature.Sensor](#blickfeld.protocol.status.Temperature.Sensor) |
| value | [float](#float) | optional | Unit: [degrees Celsius] – temperature value of the module. |
| failed_reason | [string](#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](Scan_Pattern)
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| horizontal | [ScanPattern.Horizontal](#blickfeld.protocol.config.ScanPattern.Horizontal) | optional | Refer to [ScanPattern.Horizontal](#blickfeld.protocol.config.ScanPattern.Horizontal) |
| vertical | [ScanPattern.Vertical](#blickfeld.protocol.config.ScanPattern.Vertical) | optional | Refer to [ScanPattern.Vertical](#blickfeld.protocol.config.ScanPattern.Vertical) |
| pulse | [ScanPattern.Pulse](#blickfeld.protocol.config.ScanPattern.Pulse) | optional | Refer to [ScanPattern.Pulse](#blickfeld.protocol.config.ScanPattern.Pulse) |
| frame_rate | [ScanPattern.FrameRate](#blickfeld.protocol.config.ScanPattern.FrameRate) | optional | Refer to [ScanPattern.FrameRate](#blickfeld.protocol.config.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](Sync).
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| target | [double](#double) | optional | Target frame rate during synchronization between several LiDAR devices |
| maximum | [double](#double) | optional | Read-only parameter for maximum achievable frame rate. |
| reference_time_offset | [double](#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](#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](#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](#blickfeld.protocol.config.ScanPattern.Pulse.Type) | optional | Refer to [ScanPattern.Pulse.Type](#blickfeld.protocol.config.ScanPattern.Pulse.Type) Default: EQUI_HORIZONTAL_ANGLE |
| frame_mode | [ScanPattern.Pulse.FrameMode](#blickfeld.protocol.config.ScanPattern.Pulse.FrameMode) | optional | Refer to [ScanPattern.Pulse.FrameMode](#blickfeld.protocol.config.ScanPattern.Pulse.FrameMode) Default: ONLY_UP |
| distortion_correction | [bool](#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](Scan_Pattern)
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| fov | [float](#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](#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](#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](#blickfeld.protocol.data.PointCloud.Header) | optional | Refer to [PointCloud.Header](#blickfeld.protocol.data.PointCloud.Header) |
| frame | [Frame](#blickfeld.protocol.data.Frame) | optional | Refer to [Frame](#blickfeld.protocol.data.Frame) |
| scanline | [Scanline](#blickfeld.protocol.data.Scanline) | optional | Refer to [Scanline](#blickfeld.protocol.data.Scanline) |
### PointCloud.Header
This section describes the contents of a point cloud header.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| legacy_cube_serial_number | [string](#string) | optional | Legacy serial number of the device which recorded the pointcloud |
| cube_serial_number | [string](#string) | optional | Serial number of the device which recorded the pointcloud |
| start_time_ns | [uint64](#uint64) | optional | Unit: [s] - Start timestamp of the requested pointcloud stream |
| firmware_version | [string](#string) | optional | Firmware version of the device which recorded the pointcloud |
| hardware_variant | [blickfeld.protocol.update.HardwareVariant](#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](#uint64) | optional | Incremental frame ID since startup of the device |
| scanlines | [Scanline](#blickfeld.protocol.data.Scanline) | repeated | Refer to [Scanline](#blickfeld.protocol.data.Scanline) |
| start_time_ns | [uint64](#uint64) | optional | Unit: [s] – start frame timestamp |
| scan_pattern | [blickfeld.protocol.config.ScanPattern](#blickfeld.protocol.config.ScanPattern) | optional | Refer to [ScanPattern](#blickfeld.protocol.config.ScanPattern) |
| total_number_of_points | [uint32](#uint32) | optional | Number of laser pulses emitted in this frame. |
| total_number_of_returns | [uint32](#uint32) | optional | Number of returned points recorded:
Each point of the [total_number_of_points](#blickfeld.protocol.data.Frame.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](#uint64) | optional | Scan line ID in the corresponding frame |
| frame_id | [uint64](#uint64) | optional | Frame ID of the corresponding frame |
| points | [Point](#blickfeld.protocol.data.Point) | repeated | Refer to [Point](#blickfeld.protocol.data.Point) |
| start_offset_ns | [uint64](#uint64) | optional | Unit: [ns] - start time of the scanline in relation to [Frame.start_time_ns](#blickfeld.protocol.data.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](#blickfeld.protocol.data.Point.Return).
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| id | [uint32](#uint32) | optional | Point ID in the corresponding frame |
| returns | [Point.Return](#blickfeld.protocol.data.Point.Return) | repeated | Refer to [Point.Return](#blickfeld.protocol.data.Point.Return) |
| start_offset_ns | [uint64](#uint64) | optional | Unit: [ns] - starting time of the point in relation to [Frame.start_time_ns](#blickfeld.protocol.data.Frame.start_time_ns) |
| ambient_light_level | [uint32](#uint32) | optional | Ambient light level in the direction of the point |
| direction | [Point.Direction](#blickfeld.protocol.data.Point.Direction) | optional | Refer to [Point.Direction](#blickfeld.protocol.data.Point.Direction) |
| channel_id | [uint32](#uint32) | optional | ID of the channel that detected the point |
| error_flags | [Point.ErrorFlag](#blickfeld.protocol.data.Point.ErrorFlag) | repeated | Refer to [Point.ErrorFlag](#blickfeld.protocol.data.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](#float) | optional | Unit: [rad] - azimuth angle: Angle with respect to y-z plane |
| elevation | [float](#float) | optional | Unit: [rad] - elevation angle: Angle with respect to x-y plane |
| origin | [float](#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](#uint32) | optional | ID of the return in the point |
| cartesian | [float](#float) | repeated | Unit: [m] – Cartesian coordinates of the target [x,y,z] |
| range | [float](#float) | optional | Unit: [m] – distance of target to the origin |
| intensity | [uint32](#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](#blickfeld.protocol.Request.Hello) | optional | Refer to [Request.Hello](#blickfeld.protocol.Request.Hello) |
| developer | [Request.Developer](#blickfeld.protocol.Request.Developer) | optional | Refer to [Request.Developer](#blickfeld.protocol.Request.Developer) |
| set_scan_pattern | [Request.SetScanPattern](#blickfeld.protocol.Request.SetScanPattern) | optional | Refer to [Request.SetScanPattern](#blickfeld.protocol.Request.SetScanPattern) |
| fill_scan_pattern | [Request.FillScanPattern](#blickfeld.protocol.Request.FillScanPattern) | optional | Refer to [Request.FillScanPattern](#blickfeld.protocol.Request.FillScanPattern) |
| get_scan_pattern | [Request.GetScanPattern](#blickfeld.protocol.Request.GetScanPattern) | optional | Refer to [Request.GetScanPattern](#blickfeld.protocol.Request.GetScanPattern) |
| subscribe | [stream.Subscribe](#blickfeld.protocol.stream.Subscribe) | optional | Refer to [Subscribe](#blickfeld.protocol.stream.Subscribe) |
| status | [Request.Status](#blickfeld.protocol.Request.Status) | optional | Refer to [Request.Status](#blickfeld.protocol.Request.Status) |
| _asJSON | [string](#string) | optional | Internal use only |
| accept_format | [Format](#blickfeld.protocol.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](#blickfeld.protocol.Request.SetScanPattern).
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| config | [config.ScanPattern](#blickfeld.protocol.config.ScanPattern) | optional | Refer to [ScanPattern](#blickfeld.protocol.config.ScanPattern) |
| legacy_config | [config.ScanPattern](#blickfeld.protocol.config.ScanPattern) | optional | Deprecated |
### Request.GetScanPattern
This request is used to retrieve the currently set [ScanPattern](#blickfeld.protocol.config.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](#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](#blickfeld.protocol.config.ScanPattern) | optional | Refer to [ScanPattern](#blickfeld.protocol.config.ScanPattern) |
| persist | [bool](#bool) | optional | Persists with the scan pattern and sets it after a power cycle. Default: False Default: false |
| legacy_config | [config.ScanPattern](#blickfeld.protocol.config.ScanPattern) | optional | Deprecated old 'config' due to horizontal field of view definition |
### Request.Status
This request is used for receiving the current [Status](#blickfeld.protocol.status.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](#blickfeld.protocol.Request).
Each response has the same name as the request.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| timestamp_ns | [uint64](#uint64) | optional | Unit: [ns] - timestamp when the response is sent out |
| error | [Error](#blickfeld.protocol.Error) | optional | Refer to [Error](#blickfeld.protocol.Error) |
| hello | [Response.Hello](#blickfeld.protocol.Response.Hello) | optional | Refer to [Response.Hello](#blickfeld.protocol.Response.Hello) |
| developer | [Response.Developer](#blickfeld.protocol.Response.Developer) | optional | Refer to [Response.Developer](#blickfeld.protocol.Response.Developer) |
| set_scan_pattern | [Response.SetScanPattern](#blickfeld.protocol.Response.SetScanPattern) | optional | Refer to [Response.SetScanPattern](#blickfeld.protocol.Response.SetScanPattern) |
| fill_scan_pattern | [Response.FillScanPattern](#blickfeld.protocol.Response.FillScanPattern) | optional | Refer to [Response.FillScanPattern](#blickfeld.protocol.Response.FillScanPattern) |
| get_scan_pattern | [Response.GetScanPattern](#blickfeld.protocol.Response.GetScanPattern) | optional | Refer to [Response.GetScanPattern](#blickfeld.protocol.Response.GetScanPattern) |
| event | [stream.Event](#blickfeld.protocol.stream.Event) | optional | Refer to [Event](#blickfeld.protocol.stream.Event) |
| status | [Status](#blickfeld.protocol.Status) | optional | Refer to [Response.Status](#blickfeld.protocol.Response.Status) |
| _asJSON | [string](#string) | optional | Internal use only |
### Response.Developer
Internal use only
### Response.FillScanPattern
This response is given after a request to fill a sparse [ScanPattern](#blickfeld.protocol.config.ScanPattern) has been transmitted.
It returns a scan pattern, the unset fields are filled with default values.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| config | [config.ScanPattern](#blickfeld.protocol.config.ScanPattern) | optional | Refer to [ScanPattern](#blickfeld.protocol.config.ScanPattern) |
| legacy_config | [config.ScanPattern](#blickfeld.protocol.config.ScanPattern) | optional | Deprecated |
### Response.GetScanPattern
This response is returned after a request to get the current [ScanPattern](#blickfeld.protocol.config.ScanPattern).
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| config | [config.ScanPattern](#blickfeld.protocol.config.ScanPattern) | optional | Refer to [ScanPattern](#blickfeld.protocol.config.ScanPattern) |
| legacy_config | [config.ScanPattern](#blickfeld.protocol.config.ScanPattern) | optional | Deprecated |
### Response.Hello
This response is sent out after establishing a connection.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| protocol_version | [uint32](#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](#blickfeld.protocol.data.PointCloud) | optional | Refer to [PointCloud](#blickfeld.protocol.data.PointCloud) |
| status | [blickfeld.protocol.Status](#blickfeld.protocol.Status) | optional | Refer to [Status](#blickfeld.protocol.status.Status) |
| developer | [Event.Developer](#blickfeld.protocol.stream.Event.Developer) | optional | Refer to [Event.Developer](#blickfeld.protocol.stream.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](#blickfeld.protocol.stream.Subscribe.PointCloud) | optional | Refer to [Subscribe.PointCloud](#blickfeld.protocol.stream.Subscribe.PointCloud) |
| status | [Subscribe.Status](#blickfeld.protocol.stream.Subscribe.Status) | optional | Refer to [Subscribe.Status](#blickfeld.protocol.stream.Subscribe.Status) |
| developer | [Subscribe.Developer](#blickfeld.protocol.stream.Subscribe.Developer) | optional | Refer to [Subscribe.Developer](#blickfeld.protocol.stream.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](#blickfeld.protocol.Error.Unknown) | optional | Refer to [Unknown](#blickfeld.protocol.Error.Unknown) |
| not_implemented | [Error.NotImplemented](#blickfeld.protocol.Error.NotImplemented) | optional | Refer to [NotImplemented](#blickfeld.protocol.Error.NotImplemented) |
| empty | [Error.Empty](#blickfeld.protocol.Error.Empty) | optional | Refer to [Empty](#blickfeld.protocol.Error.Empty) |
| server_implementation | [Error.ServerImplementation](#blickfeld.protocol.Error.ServerImplementation) | optional | Refer to [ServerImplementation](#blickfeld.protocol.Error.ServerImplementation) |
| invalid_request | [Error.InvalidRequest](#blickfeld.protocol.Error.InvalidRequest) | optional | Refer to [InvalidRequest](#blickfeld.protocol.Error.InvalidRequest) |
| connection_closed | [Error.ConnectionClosed](#blickfeld.protocol.Error.ConnectionClosed) | optional | Refer to [ConnectionClosed](#blickfeld.protocol.Error.ConnectionClosed) |
| outdated_server_protocol | [Error.OutdatedServerProtocol](#blickfeld.protocol.Error.OutdatedServerProtocol) | optional | Refer to [OutdatedServerProtocol](#blickfeld.protocol.Error.OutdatedServerProtocol) |
| outdated_client_protocol | [Error.OutdatedClientProtocol](#blickfeld.protocol.Error.OutdatedClientProtocol) | optional | Refer to [OutdatedClientProtocol](#blickfeld.protocol.Error.OutdatedClientProtocol) |
| scanner_busy | [Error.ScannerBusy](#blickfeld.protocol.Error.ScannerBusy) | optional | Refer to [ScannerBusy](#blickfeld.protocol.Error.ScannerBusy) |
| wrong_operation_mode | [Error.WrongOperationMode](#blickfeld.protocol.Error.WrongOperationMode) | optional | Refer to [WrongOperationMode](#blickfeld.protocol.Error.WrongOperationMode) |
| not_allowed | [Error.NotAllowed](#blickfeld.protocol.Error.NotAllowed) | optional | Refer to [NotAllowed](#blickfeld.protocol.Error.NotAllowed) |
| hardware_error | [Error.HardwareError](#blickfeld.protocol.Error.HardwareError) | optional | Refer to [HardwareError](#blickfeld.protocol.Error.HardwareError) |
| system_stop | [Error.SystemStop](#blickfeld.protocol.Error.SystemStop) | optional | Refer to [SystemStop](#blickfeld.protocol.Error.SystemStop) |
| not_found | [Error.NotFound](#blickfeld.protocol.Error.NotFound) | optional | Refer to [NotFound](#blickfeld.protocol.Error.NotFound) |
| unknown_error_code | [Error.UnknownErrorCode](#blickfeld.protocol.Error.UnknownErrorCode) | optional | Refer to [UnknownErrorCode](#blickfeld.protocol.Error.UnknownErrorCode) |
| not_in_range | [Error.NotInRange](#blickfeld.protocol.Error.NotInRange) | optional | Refer to [NotInRange](#blickfeld.protocol.Error.NotInRange) |
| time_sync_failed | [Error.TimeSyncFailed](#blickfeld.protocol.Error.TimeSyncFailed) | optional | Refer to [TimeSyncFailed](#blickfeld.protocol.Error.TimeSyncFailed) |
| no_device_discovered | [Error.NoDeviceDiscovered](#blickfeld.protocol.Error.NoDeviceDiscovered) | optional | Refer to [NoDeviceDiscovered](#blickfeld.protocol.Error.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](#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](#string) | optional | The parameter, which was not in range |
| minimum | [float](#float) | optional | Minimum value of the parameter |
| maximum | [float](#float) | optional | Maximum value of the parameter |
| requested | [float](#float) | optional | Requested value of the parameter |
| unit | [string](#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](#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](#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](#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](#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](#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](#string) | optional | Library version |
| file_time_ns | [uint64](#uint64) | optional | Unit: [ns] - File time stamp |
| language | [Client.Language](#blickfeld.protocol.file.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](#blickfeld.protocol.data.PointCloud.Header) message followed by [PointCloud.Data](#blickfeld.protocol.data.PointCloud.Data) messages.
### PointCloud.Data
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| frame | [blickfeld.protocol.data.Frame](#blickfeld.protocol.data.Frame) | optional | Refer to [PointCloud](#blickfeld.protocol.data.Frame) |
| footer | [PointCloud.Footer](#blickfeld.protocol.file.PointCloud.Footer) | optional | |
### PointCloud.Footer
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| stats | [PointCloud.Footer.Stats](#blickfeld.protocol.file.PointCloud.Footer.Stats) | optional | |
| events | [PointCloud.Footer.Event](#blickfeld.protocol.file.PointCloud.Footer.Event) | repeated | |
| stop_time_ns | [uint64](#uint64) | optional | Unit: [ns] - Stop timestamp of the requested pointcloud stream |
### PointCloud.Footer.Event
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| from_frame_id | [uint64](#uint64) | optional | |
| scan_pattern | [blickfeld.protocol.config.ScanPattern](#blickfeld.protocol.config.ScanPattern) | optional | |
### PointCloud.Footer.Stats
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| counter | [PointCloud.Footer.Stats.Counter](#blickfeld.protocol.file.PointCloud.Footer.Stats.Counter) | optional | |
### PointCloud.Footer.Stats.Counter
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| frames | [uint64](#uint64) | optional | |
| points | [uint64](#uint64) | optional | |
| returns | [uint64](#uint64) | optional | |
### PointCloud.Header
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| device | [blickfeld.protocol.data.PointCloud.Header](#blickfeld.protocol.data.PointCloud.Header) | optional | Refer to [PointCloud.Header](#blickfeld.protocol.data.PointCloud.Header) |
| client | [Client](#blickfeld.protocol.file.Client) | optional | |
### PointCloud.Metadata
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| header | [PointCloud.Header](#blickfeld.protocol.file.PointCloud.Header) | optional | |
| footer | [PointCloud.Footer](#blickfeld.protocol.file.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 |