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/common.proto
Constraint
Introduced in BSL v2.14 and firmware v1.14
Describes a constraint for a single target field
| Field | Type | Label | Description |
|---|---|---|---|
| target | Field | optional | Link to target field on which the contraint is applied |
| reason | string | optional | Human-readable reason for the constraint and its failure |
| constant | Constraint.Constant | optional | |
| polynomial | Constraint.Polynomial | optional |
Constraint.Constant
Constant constraint which is used to apply min and/or max ranges
| Field | Type | Label | Description |
|---|---|---|---|
| minimum | float | optional | Target value must be equals or higher than the specified minimum |
| maximum | float | optional | Target value must be equals or smaller than the specified maximum |
Constraint.Polynomial
Polynomial constraint which describe a value relationship to another field
| Field | Type | Label | Description |
|---|---|---|---|
| reference | Field | optional | Link to reference field. The value of the reference field is used as x input for the polynomial. |
| minimum | float | repeated | Target value must be equals or higher than the specified minimum, which is described by the specified repeated coefficients: c0 + x * c1 + x^2 * c2 .. |
| maximum | float | repeated | Target value must be equals or smaller than the specified maximum, which is described by the specified repeated coefficients: c0 + x * c1 + x^2 * c2 .. |
Field
Introduced in BSL v2.14 and firmware v1.14
Describes a protobuf field inside a (nested) message to efficiently use reflection on all supported platforms
| Field | Type | Label | Description |
|---|---|---|---|
| identifiers | Field.Identifier | repeated | Path to field in relation to given top level message. |
| scale | float | optional | Numerical scale which is applied on a field value before using it for validation. This is required to prevent floating point precision issues due to rounding, which could fail a validation. Validation example: Field value is stored as radian but is shown to the user as degree. Without scaling and rounding, a possible degree format could be rejected as it exceeded the maximum value of the radian respresentation after down-scaling. |
Field.Identifier
Describes unique identifier of (sub) field
| Field | Type | Label | Description |
|---|---|---|---|
| id | uint32 | optional | Protobuf number of field |
| key | string | optional | Protobuf key of field |
| camelcase_key | string | optional | Protobuf camelcase key of field |
HardwareModule
| Field | Type | Label | Description |
|---|---|---|---|
| serial_number | string | optional | Serial number of the hardware module |
| legacy_serial_number | string | optional | Deprecated legacy serial number format |
| version | string | optional | Hardware version of the hardware module if available. |
OptionalValueRange
| Field | Type | Label | Description |
|---|---|---|---|
| minimum | float | optional | |
| maximum | float | optional |
SoftwareVersion
| Field | Type | Label | Description |
|---|---|---|---|
| name | string | optional | Tag or reference name of the version. It is not the the name of the software. |
| revision | string | optional | The GIT revision of the software version if available. |
| ci_job_id | uint32 | optional | The unique continuous integration job ID if available. |
ValueRange
| Field | Type | Label | Description |
|---|---|---|---|
| minimum | float | optional | |
| maximum | float | optional |
Language
| Name | Number | Description |
|---|---|---|
| CPP | 1 | |
| PYTHON | 2 | |
| TYPESCRIPT | 3 |
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.11Refer to Request.SetAdvancedConfig |
| get_advanced_config | Request.GetAdvancedConfig | optional | Introduced in BSL v2.11 and firmware v1.11Refer to Request.GetAdvancedConfig |
| unsubscribe | stream.Subscribe | optional | Introduced in BSL v2.13 and firmware v1.13Unsubscribe a stream started with a Subscribe request. |
| attempt_error_recovery | Request.AttemptErrorRecovery | optional | Introduced in BSL v2.13 and firmware v1.13Refer to Request.AttemptErrorRecovery |
| get_scan_pattern_constraints | Request.GetScanPatternConstraints | optional | Introduced in BSL v2.14 and firmware v1.14Refer to Request.GetScanPatternConstraints |
| get_named_scan_patterns | Request.GetNamedScanPatterns | optional | Introduced in BSL v2.15 and firmware v1.16Refer to Request.GetNamedScanPatterns |
| store_named_scan_pattern | Request.StoreNamedScanPattern | optional | Introduced in BSL v2.15 and firmware v1.16Refer to Request.StoreNamedScanPattern |
| delete_named_scan_pattern | Request.DeleteNamedScanPattern | optional | Introduced in BSL v2.15 and firmware v1.16Refer to Request.DeleteNamedScanPattern |
| proxy_hello | Request.ProxyHello | optional | Introduced in BSL v2.16 and firmware v1.17Refer to Request.ProxyHello |
| _asJSON | string | optional | Internal use only |
| accept_format | Format | optional | Internal use only Default: PROTOBUF |
Request.AttemptErrorRecovery
Introduced in BSL v2.13 and firmware v1.13
This request can be used to attempt a re-initialization of the device if it is errored. A self test is automatically triggered after a successful re-initialization.
Request.DeleteNamedScanPattern
Introduced in BSL v2.15 and firmware v1.16
This request deletes a named scan pattern. Default scan patterns can’t be deleted.
| Field | Type | Label | Description |
|---|---|---|---|
| name | string | optional | Name |
Request.Developer
Internal use only
Request.FillScanPattern
This request is used to fill an empty or partially filled scan pattern with the required parameters. It will fill the given scan pattern with default values and return the filled scan pattern to the client. The filled scan pattern can then be set as input for Request.SetScanPattern.
| Field | Type | Label | Description |
|---|---|---|---|
| config | config.ScanPattern | optional | Refer to ScanPattern |
Request.GetAdvancedConfig
Introduced in BSL v2.11 and firmware v1.11
This request is used to retrieve the currently set Advanced.
Request.GetNamedScanPatterns
Introduced in BSL v2.15 and firmware v1.16
This request returns a list of named scan patterns.
Request.GetScanPattern
This request is used to retrieve the currently set ScanPattern.
Request.GetScanPatternConstraints
Introduced in BSL v2.14 and firmware v1.14
This request returns a list of constraints which are applied on scan patterns. The constraints define the constant and dynamic relationships between field values. The constraints are equal for a device type and firmware, but might vary for firmware releases and device variants. It is mainly used to visualize the constraints in the scan pattern configuration of the web gui.
Request.Hello
This request is used for initial communication after connecting to a device and testing the established connection.
| Field | Type | Label | Description |
|---|---|---|---|
| protocol_version | uint32 | optional | Version of the Blickfeld protocol |
| library_version | string | optional | Introduced in BSL v2.16 and firmware v1.17Library version |
| language | Language | optional | Introduced in BSL v2.16 and firmware v1.17Library language |
Request.ProxyHello
Internal use only
This request is used by internal proxy implementation to forward the correct ip address to the server.
| Field | Type | Label | Description |
|---|---|---|---|
| ip_address | string | optional | IP address of the real client |
Request.RunSelfTest
Introduced in BSL v2.10 and firmware v1.9
This request triggers a self test of the device. It validates the hardware, operates the device, and generates a report. The report is currently only accessible by developers.
Request.SetAdvancedConfig
Introduced in BSL v2.11 and firmware v1.11
This request is used for configuring the advanced config.
| Field | Type | Label | Description |
|---|---|---|---|
| config | config.Advanced | optional | Refer to Advanced |
| persist | bool | optional | Persists the config and sets it after a power cycle. Default: True Default: true |
Request.SetScanPattern
This request is used for setting a Scan Pattern. A Scan Pattern can either be set by providing a Scan Pattern configuration or a name of a named Scan Pattern.
| Field | Type | Label | Description |
|---|---|---|---|
| config | config.ScanPattern | optional | Refer to ScanPattern |
| name | string | optional | Set named Scan Pattern, refer to NamedScanPattern |
| persist | bool | optional | Persists the scan pattern and sets it after a power cycle. Default: False Default: false |
Request.Status
This request is used for receiving the current Status.
Request.StoreNamedScanPattern
Introduced in BSL v2.15 and firmware v1.16
This request sets a named scan patterns. The name has to be different of the default scan patterns and can only contain letters, numbers, space, underscore and minus.
| Field | Type | Label | Description |
|---|---|---|---|
| name | string | optional | Name |
| config | config.ScanPattern | optional | Refer to ScanPattern |
Response
This section describes the responses a client receives after sending a request to the server. For the request that corresponds to a given response, please refer to Request. Each response has the same name as the request.
| Field | Type | Label | Description |
|---|---|---|---|
| timestamp_ns | uint64 | optional | Unit: [ns] - timestamp when the response is sent out |
| error | Error | optional | Refer to Error |
| hello | Response.Hello | optional | Refer to Response.Hello |
| developer | Response.Developer | optional | Refer to Response.Developer |
| set_scan_pattern | Response.SetScanPattern | optional | Refer to Response.SetScanPattern |
| fill_scan_pattern | Response.FillScanPattern | optional | Refer to Response.FillScanPattern |
| get_scan_pattern | Response.GetScanPattern | optional | Refer to Response.GetScanPattern |
| event | stream.Event | optional | Refer to Event |
| status | Status | optional | Refer to Response.Status |
| run_self_test | Response.RunSelfTest | optional | Refer to Response.RunSelfTest |
| set_advanced_config | Response.SetAdvancedConfig | optional | Introduced in BSL v2.11 and firmware v1.11Refer to Response.SetAdvanced |
| get_advanced_config | Response.GetAdvancedConfig | optional | Introduced in BSL v2.11 and firmware v1.11Refer to Response.GetAdvanced |
| attempt_error_recovery | Response.AttemptErrorRecovery | optional | Introduced in BSL v2.13 and firmware v1.13Refer to Response.AttemptErrorRecovery |
| get_scan_pattern_constraints | Response.GetScanPatternConstraints | optional | Introduced in BSL v2.14 and firmware v1.14Refer to Response.GetScanPatternConstraints |
| get_named_scan_patterns | Response.GetNamedScanPatterns | optional | Introduced in BSL v2.15 and firmware v1.16Refer to Response.GetNamedScanPatterns |
| store_named_scan_pattern | Response.StoreNamedScanPattern | optional | Introduced in BSL v2.15 and firmware v1.16Refer to Response.StoreNamedScanPattern |
| delete_named_scan_pattern | Response.DeleteNamedScanPattern | optional | Introduced in BSL v2.15 and firmware v1.16Refer to Response.DeleteNamedScanPattern |
| proxy_hello | Response.ProxyHello | optional | Introduced in BSL v2.16 and firmware v1.17Refer to Response.ProxyHello |
| _asJSON | string | optional | Internal use only |
Response.AttemptErrorRecovery
Introduced in BSL v2.13 and firmware v1.13
This response is sent out after sending AttemptErrorRecovery.
Response.DeleteNamedScanPattern
Introduced in BSL v2.15 and firmware v1.16
This response is sent out after sending DeleteNamedScanPattern.
Response.Developer
Internal use only
Response.FillScanPattern
This response is given after a request to fill a sparse ScanPattern has been transmitted. It returns a scan pattern, the unset fields are filled with default values.
| Field | Type | Label | Description |
|---|---|---|---|
| config | config.ScanPattern | optional | Refer to ScanPattern |
Response.GetAdvancedConfig
Introduced in BSL v2.11 and firmware v1.11
This response is returned after a request to get the current Advanced.
| Field | Type | Label | Description |
|---|---|---|---|
| config | config.Advanced | optional | Refer to Advanced |
Response.GetNamedScanPatterns
Introduced in BSL v2.15 and firmware v1.16
This response is sent out after sending GetNamedScanPatterns.
| Field | Type | Label | Description |
|---|---|---|---|
| configs | config.NamedScanPattern | repeated | List of named scan patterns, refer to NamedScanPattern |
Response.GetScanPattern
This response is returned after a request to get the current ScanPattern.
| Field | Type | Label | Description |
|---|---|---|---|
| config | config.ScanPattern | optional | Refer to ScanPattern |
Response.GetScanPatternConstraints
Introduced in BSL v2.14 and firmware v1.14
This response is sent out after sending GetScanPatternConstraints.
| Field | Type | Label | Description |
|---|---|---|---|
| constraints | Constraint | repeated | List of constraints which apply for scan patterns. |
Response.Hello
This response is sent out after establishing a connection.
| Field | Type | Label | Description |
|---|---|---|---|
| protocol_version | uint32 | optional | Version of the Blickfeld Protocol |
| library_version | string | optional | Introduced in BSL v2.16 and firmware v1.17Library version |
| language | Language | optional | Introduced in BSL v2.16 and firmware v1.17Library language |
| product | config.Product | optional | Introduced in BSL v2.16 and firmware v1.17Refer to Product. |
| serial_number | string | optional | Introduced in BSL v2.16 and firmware v1.17Cube serial number |
| legacy_serial_number | string | optional | Introduced in BSL v2.16 and firmware v1.17Deprecated legacy serial number |
| firmware | Response.Hello.Firmware | optional | Introduced in BSL v2.16 and firmware v1.17Refer to Firmware. |
| hardware_modules | Response.Hello.HardwareModulesEntry | repeated | Introduced in BSL v2.16 and firmware v1.17Hardware module map, where the key is the name and the object is the HardwareModule. |
Response.Hello.Firmware
Introduced in BSL v2.16 and firmware v1.17
Contains all firmware names, versions, and revisions.
| Field | Type | Label | Description |
|---|---|---|---|
| version | SoftwareVersion | optional | Baseline version of firmware. Refer to SoftwareVersion. |
| module_versions | Response.Hello.Firmware.ModuleVersionsEntry | repeated | Version of software modules. The key of the map is the name and the object is the SoftwareVersion. |
Response.Hello.Firmware.ModuleVersionsEntry
| Field | Type | Label | Description |
|---|---|---|---|
| key | string | optional | |
| value | SoftwareVersion | optional |
Response.Hello.HardwareModulesEntry
| Field | Type | Label | Description |
|---|---|---|---|
| key | string | optional | |
| value | HardwareModule | optional |
Response.ProxyHello
Internal use only
Response.RunSelfTest
Introduced in BSL v2.10 and firmware v1.9
This response is returned after a self test. The success flag indicates if the hardware is fully operational. The generated report is currently only accessible by developers.
| Field | Type | Label | Description |
|---|---|---|---|
| success | bool | optional |
Response.SetAdvancedConfig
Introduced in BSL v2.11 and firmware v1.11
This response is sent out after setting an SetAdvancedConfig.
Response.SetScanPattern
This response is sent out after setting a scan pattern.
Response.StoreNamedScanPattern
Introduced in BSL v2.15 and firmware v1.16
This response is sent out after sending StoreNamedScanPattern.
Format
The format type of response is an undocumented, internal feature required for the REST API.
| Name | Number | Description |
|---|---|---|
| PROTOBUF | 1 | |
| JSON | 2 |
blickfeld/error.proto
Error
| Field | Type | Label | Description |
|---|---|---|---|
| unknown | Error.Unknown | optional | Refer to Unknown |
| not_implemented | Error.NotImplemented | optional | Refer to NotImplemented |
| empty | Error.Empty | optional | Refer to Empty |
| server_implementation | Error.ServerImplementation | optional | Refer to ServerImplementation |
| invalid_request | Error.InvalidRequest | optional | Refer to InvalidRequest |
| connection_closed | Error.ConnectionClosed | optional | Refer to ConnectionClosed |
| outdated_server_protocol | Error.OutdatedServerProtocol | optional | Refer to OutdatedServerProtocol |
| outdated_client_protocol | Error.OutdatedClientProtocol | optional | Refer to OutdatedClientProtocol |
| scanner_busy | Error.ScannerBusy | optional | Refer to ScannerBusy |
| wrong_operation_mode | Error.WrongOperationMode | optional | Refer to WrongOperationMode |
| not_allowed | Error.NotAllowed | optional | Refer to NotAllowed |
| hardware_error | Error.HardwareError | optional | Refer to HardwareError |
| system_stop | Error.SystemStop | optional | Refer to SystemStop |
| not_found | Error.NotFound | optional | Refer to NotFound |
| unknown_error_code | Error.UnknownErrorCode | optional | Refer to UnknownErrorCode |
| not_in_range | Error.NotInRange | optional | Refer to NotInRange |
| time_sync_failed | Error.TimeSyncFailed | optional | Refer to TimeSyncFailed |
| no_device_discovered | Error.NoDeviceDiscovered | optional | Refer to NoDeviceDiscovered |
| not_supported | Error.NotSupported | optional | Refer to NotSupported |
| connection_abort | Error.ConnectionAbort | optional | Refer to ConnectionAbort |
Error.ConnectionAbort
During reading, the connection to the device got aborted.
| Field | Type | Label | Description |
|---|---|---|---|
| details | string | optional |
Error.ConnectionClosed
The server closed the connection.
Error.Empty
The server sent an empty message.
Error.HardwareError
The device is in an error state and cannot be operated. Attempt to power-cycle the device or use diagnostic software to read out the hardware state.
Error.InvalidRequest
Validation of the sent request failed, please send a request with-in a valid range.
| Field | Type | Label | Description |
|---|---|---|---|
| validation_error | string | optional | Validation error string |
| constraints | Constraint | repeated | Introduced in BSL v2.14 and firmware v1.14Contains list of failed constraints. The validation_error field contains a human-readable output of the constraint validation. |
Error.NoDeviceDiscovered
No device has been discovered. Check the network connection and power supply of the device. The ‘discover’ requests may have been blocked by a local or a network firewall.
Error.NotAllowed
The requested operation is not allowed.
Error.NotFound
The requested data is not available. Please check the request parameters.
Error.NotImplemented
The firmware on the device is not compatible with the BSL version. Update the device or downgrade the BSL.
| Field | Type | Label | Description |
|---|---|---|---|
| reason | string | optional | Description why this is not implemented Default: No detailed reason available. |
Error.NotInRange
The requested parameter is not within the valid range.
| Field | Type | Label | Description |
|---|---|---|---|
| parameter | string | optional | The parameter, which was not in range |
| minimum | float | optional | Minimum value of the parameter |
| maximum | float | optional | Maximum value of the parameter |
| requested | float | optional | Requested value of the parameter |
| unit | string | optional | Unit of the parameter |
Error.NotSupported
The action is not supported by the current client or server API. Check the versions of the client and firmware software and read the changelog.
| Field | Type | Label | Description |
|---|---|---|---|
| reason | string | optional | Description why this is not supported Default: No detailed reason available. |
Error.OutdatedClientProtocol
The protocol of the server is too new. Please update the client software.
| Field | Type | Label | Description |
|---|---|---|---|
| required_version | uint32 | optional | Version that is required |
Error.OutdatedServerProtocol
The protocol of the client is too new. Please update the device.
| Field | Type | Label | Description |
|---|---|---|---|
| required_version | uint32 | optional | Version that is required |
Error.ScannerBusy
The device is currently busy with another operation. Cancel it and try again.
Error.ServerImplementation
The server failed to process the request.
Error.SystemStop
The device stopped unexpectedly and can no longer be operated. Attempt to power cycle the device or use diagnostic software to read-out the hardware state.
Error.TimeSyncFailed
The time synchronization failed. The NTP daemon failed or timed out.
| Field | Type | Label | Description |
|---|---|---|---|
| ntp_daemon_log | string | optional | Log of the NTP daemon |
Error.Unknown
Unknown error. Please consult the Blickfeld support team for further information.
| Field | Type | Label | Description |
|---|---|---|---|
| description | string | optional | Description of the unknown error |
Error.UnknownErrorCode
Unknown Error. Please contact the Blickfeld support team and make sure to use compatible BSL and FW versions.
| Field | Type | Label | Description |
|---|---|---|---|
| error_code | uint32 | optional | Error code |
Error.WrongOperationMode
The device is set to a different operation mode. Perhaps it is currently being used by another application. Change the operation mode and try again if no one else is using it.
blickfeld/options.proto
File-level Extensions
| Extension | Type | Base | Number | Description |
| ——— | —- | —- | —— | ———– |
| allow_sparse | bool | .google.protobuf.FieldOptions | 50007 | Default: false |
| d_max | double | .google.protobuf.FieldOptions | 50001 | Default: inf |
| d_min | double | .google.protobuf.FieldOptions | 50000 | Default: -inf |
| legacy_field_id | uint64 | .google.protobuf.FieldOptions | 50010 | |
| length | sint32 | .google.protobuf.FieldOptions | 50004 | Default: 2147483647 |
| max_length | sint32 | .google.protobuf.FieldOptions | 50009 | Default: 2147483647 |
| min_length | sint32 | .google.protobuf.FieldOptions | 50008 | Default: 0 |
| optional | bool | .google.protobuf.FieldOptions | 50006 | Default: false |
| regex | string | .google.protobuf.FieldOptions | 50005 | Default: .* |
| ui_decimal_places | uint32 | .google.protobuf.FieldOptions | 50014 | Default: 0 |
| ui_scale | double | .google.protobuf.FieldOptions | 50013 | Scaling of field value in user interfaces (UIs). Example: rad-to-degree conversions. Default: 1 |
| ui_unit | string | .google.protobuf.FieldOptions | 50012 | Unit of field value in user interfaces (UIs). |
| unit | string | .google.protobuf.FieldOptions | 50011 | Unit of field value |
| e_desc | string | .google.protobuf.MessageOptions | 60000 | Error description Default: No additional error description available. |
| generate | config.Generate | .google.protobuf.MessageOptions | 60003 | |
| help | string | .google.protobuf.MessageOptions | 60001 | Help description |
| secure | config.Secure | .google.protobuf.MessageOptions | 60002 | |
| optional_one_of | bool | .google.protobuf.OneofOptions | 50006 | Default: false |
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.12Refer to Processing |
| server | Advanced.Server | optional | Introduced in BSL v2.13 and firmware v1.13Refer to Server |
| time_synchronization | Advanced.TimeSynchronization | optional | Introduced in BSL v2.18 and firmware v1.19Refer to TimeSynchronization |
Advanced.Detector
The behavior of the detector can be adjusted to improve the performance under extreme environmental conditions, e.g. static setup with strong daylight or basement rooms without daylight.
| Field | Type | Label | Description |
|---|---|---|---|
| sensitivity | float | optional | Relatively influences the sensitivity of the detector. Higher values might also result into range loss. It is recommended to validate the noise filter parameters after changes to this setting. Default: 1 |
Advanced.Processing
Introduced in BSL v2.12 and firmware v1.12
Processing parameters are set at the factory after calibration. Changing these values invalidates the factory calibration.
| Field | Type | Label | Description |
|---|---|---|---|
| range_offset | float | optional | in [m] Default: 0 |
| imu_static_rotation_offset | float | repeated | Introduced in BSL v2.19 and firmware v1.20in [rad] - Offset rotation matrix for acceleration of IMU. Can be used to calibrate the accelerometer e.g. on a flat surface. |
| horizontal_phase_offset | float | optional | Introduced in BSL v2.19.5 and firmware v1.21.1in [s] - Correction for phase offset in the horizontal field of view. This parameter might be adjusted in the field if the upper and lower half of the frame drifted horizontally. Default: 0 |
Advanced.Server
Introduced in BSL v2.13 and firmware v1.13
Parameters, which control the server behavior.
| Field | Type | Label | Description |
|---|---|---|---|
| default_point_cloud_subscription | blickfeld.protocol.stream.Subscribe.PointCloud | optional | Overwrite default point cloud subscription. Can still be overridden with client requests. |
Advanced.TimeSynchronization
Introduced in BSL v2.18 and firmware v1.19
Activate or deactivate synchronization and change parameters
| Field | Type | Label | Description |
|---|---|---|---|
| ntp | Advanced.TimeSynchronization.NTP | optional | If this field is set, NTP synchronization is activated, which is the default configuration. Refer to NTP |
| ptp | Advanced.TimeSynchronization.PTP | optional | If this field is set, PTP synchronization is activated and NTP synchronization is deactivated. Refer to PTP |
Advanced.TimeSynchronization.NTP
The Blickfeld devices can use an NTPv4 client to synchronize the local device time to a time server. NTP can achieve synchronization accuracy below one millisecond for measurement results in local networks.
| Field | Type | Label | Description |
|---|---|---|---|
| servers | string | repeated | Specify list of NTP server. By default, debian pool NTP servers are used. |
Advanced.TimeSynchronization.PTP
The Blickfeld devices can use a PTP client to synchronize the local device time to a time server. PTP can achieve an higher accuracy than NTP in local networks.
| Field | Type | Label | Description |
|---|---|---|---|
| domain | uint32 | optional | PTP domain number. Default: 0 |
| delay_mechanism | Advanced.TimeSynchronization.PTP.DelayMechanism | optional | Delay detection mode used Default: E2E |
| unicast_destinations | string | repeated | Specify unicast slave addresses for unicast master operation, or unicast master addresses for slave operation. If this is set unicast mode will be activated. |
Advanced.TimeSynchronization.PTP.DelayMechanism
| Name | Number | Description |
|---|---|---|
| E2E | 1 | End to end delay detection |
| P2P | 2 | Peer to peer delay detection |
blickfeld/config/algorithm.proto
Algorithm
Introduced in BSL v2.17 and firmware v1.18
This section describes configuration of on-device algorithms.
| Field | Type | Label | Description |
|---|---|---|---|
| background_subtraction | Algorithm.BackgroundSubtraction | optional | Refer to BackgroundSubtraction |
| neighbor_filter | Algorithm.NeighborFilter | optional | Refer to NeighborFilter |
| static_transformation | Algorithm.StaticTransformation | optional | Refer to StaticTransformation |
Algorithm.BackgroundSubtraction
Introduced in firmware v1.16
This message configures the background subtraction.
The algorithm uses a configurable number of reference frames to estimate static points (background) in the scene. Once the number of reference frames are processed, it removes all static points from the point cloud output. The resulting point cloud then only contains the non-static points (foreground). Points that are a initially part of the foreground and but then stop moving, will be added to the background and thus disappear after a certain amount of time, which is given by the exponential decay rate parameter. Conversely, if an object that is already part of the background suddenly starts moving, it will be added to the foreground.
| Field | Type | Label | Description |
|---|---|---|---|
| initialization_frames | uint32 | optional | Number of frames to initialize the background with Default: 10 |
| exponential_decay_rate | float | optional | Controls how fast objects switch between foreground and background. Exponential decay factor. Default: 0.0025 |
Algorithm.NeighborFilter
Introduced in firmware v1.18
The neighbor filter is a simple noise filter, which uses neighboring returns in the scan pattern to decide if returns should be filtered.
The algorithm iterates through all returns and removes all, which have zero neighbors. A neighbor return must be:
directly to the left / to the right / above / below the current return in the scan pattern
close to the current return. The maximum range, used for this condition, is defined by the angle spacing of the scan pattern and the range of the current return. As with higher distance, neighboring returns are expected to be further away.
No parameters can be configured at the moment.
Algorithm.StaticTransformation
Introduced in firmware v1.18
This message configures a static geometric transformation.
The algorithm applies a static rotation and translation to the point cloud output.
The rotation matrix R is expected to be a 3 x 3 matrix serialized in row major order.
Rotation in matrix representation:
| R | ||
|---|---|---|
| r1,1 | r1,2 | r1,3 |
| r2,1 | r2,2 | r2,3 |
| r3,1 | r3,2 | r3,3 |
Rotation in serialized representation:
R = [r1,1, r1,2, … r3,2, r3,3]
The translation vector T is expected to be a 3 x 1 vector.
Translation in vector representation:
| T |
|---|
| t1 |
| t2 |
| t3 |
Translation in serialized representation:
T = [t1, t2, t3] = [x, y, z]
| Field | Type | Label | Description |
|---|---|---|---|
| rotation_matrix | float | repeated | rotation matrix R in serialized representation. |
| translation_vector | float | repeated | translation vector T in serialized representation. |
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 |
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:
Default scan patterns: Each device has default scan patterns, these are saved on the device with the firmware. They are not changeable.
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 |
blickfeld/config/product.proto
Product
Product variant
| Name | Number | Description |
|---|---|---|
| PRODUCT_CUBE | 0 | |
| PRODUCT_CUBE_RANGE | 2 |
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.11Refer 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.11Refer to Filter.Noise |
| delete_points_without_returns | bool | optional | Introduced in BSL v2.16 and firmware v1.17All points without any returns are filtered if this setting is true. With active algorithms, such as background subtraction, this can reduce the bandwidth significantly. Note: It is recommended to not estimate required network bandwidths when this setting is active. In scenarios, where from one frame to another, all points have returns (e.g. due to environmental changes), the peak bandwidths might increase significantly. This could result, in these scenarios, in frame losses. Default: false |
ScanPattern.Filter.Noise
Introduced in BSL v2.11 and firmware v1.11
This is a preliminary interface to control the noise filter on the device. All points, which have a lower intensity than the minimum intensity calculated by this filter will be filtered out.
Changed in firmware v1.15. Please re-adjust filter configurations in scan patterns.
The internal algorithm implements a non-linear function, which describes the noise level for different ambient light levels. The function can be scaled with the gain and shifted with the offset.
Before firmware v1.15
The formula is: minimum_intensity = offset + gain * point.ambient_light_level, where the point.ambient_light_level is the ambient light level of the point the laser shoots at.
| Field | Type | Label | Description |
|---|---|---|---|
| offset | uint32 | optional | Can be seen as minimum intensity filter, if there is no ambient light. |
| gain | float | optional | The gain scales a non-linear function, which uses the ambient light level of the point the laser shoots at, as an input. |
| enable | bool | optional | Introduced in BSL v2.17 and firmware v1.18This flag can be used to disable the internal noise filter completely. By default, the noise filter is enabled. Default: true |
ScanPattern.FrameRate
This section defines the target frame rate for synchronization between several LiDAR devices. The feature is described in the Time synchronization documentation.
| Field | Type | Label | Description |
|---|---|---|---|
| target | double | optional | Target frame rate during synchronization between several LiDAR devices |
| maximum | double | optional | Read-only parameter for maximum achievable frame rate. |
| reference_time_offset | double | optional | In [s]. Adds a constant value to the Unix reference time, starting from 00:00:00 UTC on January 1, 1970. It can be used to compensate delays or to interleave LiDAR devices. Default: 0 Default: 0 |
ScanPattern.Horizontal
This section defines the movement of the horizontal mirror. The mirror moves continuously with its own frequency. Each half-oscillation period of the mirror results in one scan line.
| Field | Type | Label | Description |
|---|---|---|---|
| fov | float | optional | Unit: [rad] – optical field of view of the horizontal mirror. Note: In v2.2* and below, this was defined as a mechanical FoV. |
ScanPattern.Pulse
This section defines the pattern in which the laser pulses and captures sample points
| Field | Type | Label | Description |
|---|---|---|---|
| angle_spacing | float | optional | Unit: [rad] – This defines the angle within which the horizontal mirror moves between two laser pulses. This parameter therefore defines the horizontal sampling resolution. |
| type | ScanPattern.Pulse.Type | optional | Refer to ScanPattern.Pulse.Type Default: INTERLEAVE |
| frame_mode | ScanPattern.Pulse.FrameMode | optional | Refer to ScanPattern.Pulse.FrameMode Default: COMBINE_UP_DOWN |
| distortion_correction | bool | optional | This parameter defines whether the distortion correction is applied when calculating the laser pulse angles. Default: True Default: true |
| custom | ScanPattern.Pulse.Custom | optional | Introduced in BSL v2.15 and firmware v1.16Refer 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. |
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 |
blickfeld/data/algorithm.proto
Algorithm
Introduced in BSL v2.17 and firmware v1.18
This section describes the additional data output of on-device algorithms. The data is attached to the frame.
| Field | Type | Label | Description |
|---|---|---|---|
| background_subtraction | Algorithm.BackgroundSubtraction | optional | Refer to BackgroundSubtraction. |
| neighbor_filter | Algorithm.NeighborFilter | optional | Refer to NeighborFilter. |
| static_transformation | Algorithm.StaticTransformation | optional | Refer to StaticTransformation. |
| execution_time | float | optional | Execution time of the algorithm in [s] |
Algorithm.BackgroundSubtraction
The description of the algorithm can be found at config.Algorithm.BackgroundSubtraction.
The algorithm does not output any additional information. It subtracts returns from the main frame.
Algorithm.NeighborFilter
The description of the algorithm can be found at config.Algorithm.NeighborFilter.
The algorithm does not output any additional information. It subtracts returns from the main frame.
Algorithm.StaticTransformation
The description of the algorithm can be found at config.Algorithm.StaticTransformation.
The algorithm does not output any additional information. It transforms the cartesian coordinates in the frame.
blickfeld/data/frame.proto
Frame
This section describes the contents of a point cloud frame.
| Field | Type | Label | Description |
|---|---|---|---|
| id | uint64 | optional | Incremental frame ID since startup of the device |
| start_time_ns | uint64 | optional | Unit: [s] – start frame timestamp |
| scan_pattern | blickfeld.protocol.config.ScanPattern | optional | Refer to ScanPattern |
| is_ramp_up_phase | bool | optional | Introduced in BSL v2.16 and firmware v1.17If the frame_mode in the scan pattern is set to SEPARATE, this value indicates if the given frame was captured during up-ramping or down-ramping. |
| total_number_of_points | uint32 | optional | Number of laser pulses emitted in this frame. |
| total_number_of_returns | uint32 | optional | Number of returned points recorded: Each point of the total_number_of_points can produce several returns. |
| scanlines | Scanline | repeated | Refer to Scanline |
| packed | Frame.Packed | optional | Introduced in BSL v2.16 and firmware v1.17Refer to Packed |
| algorithms | Algorithm | repeated | Introduced in BSL v2.17 and firmware v1.16Refer to data.Algorithm. Each algorithm configured can output additional data, which is provided with this field. |
Frame.Packed
Introduced in BSL v2.16 and firmware v1.17
This format returns point clouds as flat binary structures. These can be efficiently encoded & decoded, which increases the performance on low-performance clients significantly. The network bandwidth is usually slightly higher as the data is not encoded.
Note: The reference frame concept is handled differently for packed structures. To activate the packed format, it is sufficient to set an empty packed message in the reference frame. The requested fields need to be selected in the scanlines structure. Refer to REF_FRAME_PACKED in the client implementations.
| Field | Type | Label | Description |
|---|---|---|---|
| length | uint32 | optional | Length of arrays |
| cartesian | bytes | optional | Cartesian coordinates. 3-dimensional array in row-major format with [x, y, z] tuples. Unit: [m]. Type: Float32. Byte Order: Big Endian. |
| direction | bytes | optional | Polar coordinates. 2-dimensional array in row-major format with [azimuth, elevation] tuples. Unit: [rad]. Type: Float32. Byte Order: Big Endian. |
| range | bytes | optional | Distance to the return. 1-dimensional array. Unit: [m]. Type: Float32. Byte Order: Big Endian. |
| intensity | bytes | optional | Intensity of the returned laser pulse. 1-dimensional array. Type: UInt32. Byte Order: Big Endian. |
| ambient_light_level | bytes | optional | Ambient light level in the direction of the point. 1-dimensional array. Type: UInt32. Byte Order: Big Endian. |
| start_offset_ns | bytes | optional | Starting time of the point in relation to Frame.start_time_ns. 1-dimensional array. Unit: [ns]. Type: UInt64. Byte Order: Big Endian. |
| point_id | bytes | optional | Unique point identifier within a frame and scan pattern. 1-dimensional array. Type: UInt32. Byte Order: Big Endian. |
| channel_id | bytes | optional | Identifier of the channel that detected the point. 1-dimensional array. Type: UInt8. |
| return_id | bytes | optional | Identifier of the return. Note: Returns are ordered by intensity not by distance. 1-dimensional array. Type: UInt8. |
blickfeld/data/imu.proto
IMU
Introduced in BSL v2.18 and firmware v1.19
The Cube has an on-board IMU, which can be used for e.g. mapping applications or static auto-leveling.
| Field | Type | Label | Description |
|---|---|---|---|
| start_time_ns | uint64 | optional | Unit: [ns] – start timestamp of data. The start_offset_ns in each sample refers to this value. The timestamp is synchronized to the ones in point cloud frames. |
| samples | IMU.Sample | repeated | Refer to Sample |
| packed | IMU.Packed | optional | Refer to Packed |
IMU.Packed
| Field | Type | Label | Description |
|---|---|---|---|
| length | uint32 | optional | Length of arrays |
| start_offset_ns | bytes | optional | Starting time of the point in relation to Data.start_time_ns. 1-dimensional array. Unit: [ns]. Type: UInt64. Byte Order: Big Endian. |
| acceleration | bytes | optional | Accerlation. 3-dimensional array in row-major format with [x, y, z] tuples. Unit: [g]. Type: Float32. Byte Order: Big Endian. |
| angular_velocity | bytes | optional | Angular velocity, measured with gyroscope. 3-dimensional array in row-major format with [x, y, z] tuples. Unit: [rad/s]. Type: Float32. Byte Order: Big Endian. |
IMU.Sample
Describes a single IMU state. Data rate is approx. 1.125 khz.
| Field | Type | Label | Description |
|---|---|---|---|
| start_offset_ns | uint64 | optional | Unit: [ns] – Offset to start_time_ns |
| acceleration | float | repeated | Unit: [g] - Format: [x,y,z] - Measured acceleration for 3-axes. |
| angular_velocity | float | repeated | Unit: [rad/s] - Format: [x,y,z] - Measured angular velocity by gyroscope for 3-axes. |
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. |
blickfeld/data/point_cloud.proto
PointCloud
A point cloud object can contain either a full frame or a single scan line.
| Field | Type | Label | Description |
|---|---|---|---|
| header | PointCloud.Header | optional | Refer to PointCloud.Header |
| frame | Frame | optional | Refer to Frame |
| scanline | Scanline | optional | Refer to Scanline |
PointCloud.Header
This section describes the contents of a point cloud header.
| Field | Type | Label | Description |
|---|---|---|---|
| legacy_cube_serial_number | string | optional | Legacy serial number of the device which recorded the pointcloud |
| cube_serial_number | string | optional | Serial number of the device which recorded the pointcloud |
| start_time_ns | uint64 | optional | Unit: [s] - Start timestamp of the requested pointcloud stream |
| firmware_version | string | optional | Firmware version of the device which recorded the pointcloud |
| hardware_variant | blickfeld.protocol.update.HardwareVariant | optional | Hardware variant of the device which recorded the pointcloud |
| subscription | blickfeld.protocol.stream.Subscribe.PointCloud | optional | Introduced in BSL v2.16 and firmware v1.17Used & merged subscription for stream |
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 |
blickfeld/file/general.proto
Client
| Field | Type | Label | Description |
|---|---|---|---|
| library_version | string | optional | Library version |
| file_time_ns | uint64 | optional | Unit: [ns] - File time stamp |
| language | blickfeld.protocol.Language | optional | Used library language for file creation |
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 |
blickfeld/status/imu.proto
IMU
Introduced in BSL v2.18 and firmware v1.19
This section defines the status of the IMU.
| Field | Type | Label | Description |
|---|---|---|---|
| static_state | IMU.StaticState | optional |
IMU.StaticState
| Field | Type | Label | Description |
|---|---|---|---|
| acceleration | float | repeated |
blickfeld/status/main.proto
Status
This section contains the status messages of the two deflection mirrors and the temperature sensors in the device.
| Field | Type | Label | Description |
|---|---|---|---|
| scanner | status.Scanner | optional | Refer to Scanner |
| temperatures | status.Temperature | repeated | Refer to Temperature |
| server | status.Server | optional | Refer to Client |
| imu | status.IMU | optional | Introduced in BSL v2.18 and firmware v1.19Refer to IMU |
| time_synchronization | status.TimeSynchronization | optional | Introduced in BSL v2.18 and firmware v1.19Refer to TimeSynchronization |
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. |
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 |
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 |
blickfeld/status/time_synchronization.proto
TimeSynchronization
Introduced in BSL v2.18 and firmware v1.19
This section defines the synchronization status of the server.
| Field | Type | Label | Description |
|---|---|---|---|
| state | TimeSynchronization.State | optional | |
| offset_from_master | float | optional | Current offset value from master device in seconds. NTP: time offset (seconds) in loopstats PTP: It is the main output of the PTP engine that is in the worker state. This value is the input for clock corrections in the clock servo algorithms. This value is typically measured when estimating the performance of the worker device. |
| ntp | TimeSynchronization.NTP | optional | Refer to NTP |
| ptp | TimeSynchronization.PTP | optional | Refer to PTP |
TimeSynchronization.NTP
| Field | Type | Label | Description |
|---|---|---|---|
| frequency_offset | float | optional | frequency offset (parts per million - PPM) as in loopstats |
| rms_jitter | float | optional | RMS jitter (seconds) as in loopstats |
| allan_deviation | float | optional | Allan deviation (PPM) as in loopstats |
| clock_discipline_time_constant | float | optional | clock discipline time constant as in loopstats |
TimeSynchronization.PTP
| Field | Type | Label | Description |
|---|---|---|---|
| state | string | optional | ONLY AVAILABLE FOR PTP, NTP doesnt have a state Follwing states can occur: init: Initializing, flt: Faulty, lstn_init: Listening (first time), lstn_reset: Listening (subsequent reset), pass: Passive (not best master, not announcing), uncl: Uncalibrated, slv: Worker, pmst: Pre-master, mst: Master (active), dsbl: Disabled, ? (unk): Unknown state |
| clock_id | string | optional | TODO Find out for NTP!! Clock ID Port identity of the current best master, as defined by IEEE 1588 standard. This ID is the local clock's ID if the local clock is the best master. This parameter is displayed as clock_id or port (host). Port is the PTP clock port number, not the User Datagram Protocol (UDP) port numbers. The clock ID is an Extended Unique Identifier (EUI)-64 64-bit ID, converted from the 48-bit MAC address, by inserting 0xfffe at the middle of the MAC address. |
| one_way_delay | float | optional | One-way delay Current value of one-way delay (or mean-path delay) in seconds, calculated by the ptpd daemon that is in the worker state from the delay request and delay response message exchange. Note: If this value remains at zero, it means that no delay response messages are being received, which might be because of a network issue. |
| slave_to_master | float | optional | Slave to master Intermediate offset value (seconds) extracted from the delay request and delay response message exchange. This value is used for computing one-way delay. If the last value was rejected by a filter, the previous value is shown in the log file. This value is zero (0) if the delay response messages are not received. |
| master_to_slave | float | optional | Master to slave Intermediate offset value (seconds) extracted from the sync messages. This value is used for computing the offset value from the master devices. If the last value was rejected by a filter, the previous value is shown in the log file. |
| observed_drift | float | optional | Observed drift The frequency difference between the worker clock and the master clock as measured by the integral accumulator of the clock control proportional integral (PI) servo model. This value stabilizes when the clock offset value is stabilized, and this value is used to detect clock stability. |
| last_packet_received | string | optional | Last packet Received This field shows which message was received last. It displays S for sync messages and D for delay response messages. If a worker device logs no D entries, it means that the worker device is not receiving delay response messages because of network issue. |
TimeSynchronization.State
| Name | Number | Description |
|---|---|---|
| STOPPED | 1 | |
| INITIALIZING | 2 | |
| SYNCED | 3 | |
| FAILED | 4 |
blickfeld/stream/connection.proto
Subscribe
This section describes the different streams to which it is possible to subscribe. A stream regularly provides data or status updates for the user. The events will not be pushed automatically to the BSL; the client has to retrieve them.
| Field | Type | Label | Description |
|---|---|---|---|
| point_cloud | Subscribe.PointCloud | optional | Refer to Subscribe.PointCloud |
| status | Subscribe.Status | optional | Refer to Subscribe.Status |
| developer | Subscribe.Developer | optional | Refer to Subscribe.Developer |
| raw_file | Subscribe.RawFile | optional | Refer to Subscribe.RawFile |
| imu | Subscribe.IMU | optional | Introduced in BSL v2.18 and firmware v1.19Refer to Subscribe.IMU |
Subscribe.Developer
Internal use only
Subscribe.IMU
Introduced in BSL v2.18 and firmware v1.19
The Cube has an on-board IMU, which can be used for e.g. mapping applications or static auto-leveling. A stream can be requested with this subscription. The default rate is approx. 1.125 kHz and is provided in bursts. The timestamps inside the protocol are synchronized to the ones in point cloud frames.
| Field | Type | Label | Description |
|---|---|---|---|
| packed_format | bool | optional | Request a packed binary format. This is currently used for efficent Python numpy decoding. Default: false |
Subscribe.PointCloud
This request is used for subscribing to a point cloud stream.
| Field | Type | Label | Description |
|---|---|---|---|
| reference_frame | blickfeld.protocol.data.Frame | optional | Introduced in BSL v2.10 and firmware v1.9If 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.9Refer to ScanPattern.Filter. Overrides parameters of scan pattern. |
| algorithms | blickfeld.protocol.config.Algorithm | repeated | Introduced in BSL v2.17 and firmware v1.16Refer to config.Algorithm. Sets algorithms, which are initialized, configured for the stream and are executed on each frame in the post-processing on the device. |
| prepend_advanced_config_algorithms | bool | optional | Introduced in BSL v2.17 and firmware v1.16With the server.default_point_cloud_subscription algorithms can be persisted on the device and they are by default prepended to the list of sent algorithms in the subscribe request. This behaviour can be disabled with this field to e.g. disable or overwrite all algorithms. Default: true |
Subscribe.RawFile
Introduced in BSL v2.13 and firmware v1.13
This request is used for subscribing to a raw file stream. The requested stream is directly packed in the Blickfeld data format and only raw bytes are sent to the client, which it should write sequentially in a file. An Unsubscribe request with the same request data must be sent to properly end the file stream. The request raw file stream is ended with an EndOfStream event.
| Field | Type | Label | Description |
|---|---|---|---|
| point_cloud | Subscribe.PointCloud | optional | Subscribe to a raw point cloud stream. Refer to Subscribe.PointCloud. |
Subscribe.Status
This request is used for subscribing to a status stream.
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.13Raw 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.13Refer to EndOfStream |
| imu | blickfeld.protocol.data.IMU | optional | Introduced in BSL v2.18 and firmware v1.19Refer to IMU |
Event.Developer
Internal use only
Event.EndOfStream
Introduced in BSL v2.13 and firmware v1.13
Event to indicate the end of stream. This is called after an Unsubscribe request. No further events will arrive for the subscribed stream after this event.
| Field | Type | Label | Description |
|---|---|---|---|
| subscription | Subscribe | optional | Ended subscription. Refer to Subscribe. |
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 |
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 |