Client files for Qb2 Firmware v2.2.3 (01.08.2024)

doc/antora.yml

@@ -1,4 +1,4 @@
-display_version: v2.1
+display_version: v2.2
 name: Qb2
 nav:
 - modules/ROOT/nav.adoc
@@ -8,4 +8,4 @@ nav:
 - modules/developer/nav.adoc
 - modules/service_and_maintenance/nav.adoc
 title: Qb2
-version: v2.1
+version: v2.2

doc/modules/developer/nav.adoc

@@ -121,6 +121,7 @@
 ****** xref:protocol:blickfeld/percept_pipeline/data/coordinate_system.adoc[Coordinate System]
 ****** xref:protocol:blickfeld/percept_pipeline/data/health.adoc[Health]
 ****** xref:protocol:blickfeld/percept_pipeline/data/point_cloud_type.adoc[Point Cloud Type]
+****** xref:protocol:blickfeld/percept_pipeline/data/point_type.adoc[Point Type]
 ****** xref:protocol:blickfeld/percept_pipeline/data/state.adoc[State]
 ***** services
 ****** xref:protocol:blickfeld/percept_pipeline/services/data_source.adoc[Data Source]

doc/modules/protocol/nav.adoc

@@ -101,6 +101,7 @@
 ***** xref:protocol:blickfeld/percept_pipeline/data/coordinate_system.adoc[Coordinate System]
 ***** xref:protocol:blickfeld/percept_pipeline/data/health.adoc[Health]
 ***** xref:protocol:blickfeld/percept_pipeline/data/point_cloud_type.adoc[Point Cloud Type]
+***** xref:protocol:blickfeld/percept_pipeline/data/point_type.adoc[Point Type]
 ***** xref:protocol:blickfeld/percept_pipeline/data/state.adoc[State]
 **** services
 ***** xref:protocol:blickfeld/percept_pipeline/services/data_source.adoc[Data Source]

doc/modules/protocol/pages/blickfeld/core_processing/data/frame.adoc

@@ -53,5 +53,10 @@ Type: UInt32
 3+| Unix timestamp of points. 
 Type: UInt64
 
+.2+| *metadata* | optional bytes| - | - 
+3+| Arbitrary metadata for annotation of the binary data fields. 
+1-dimensional array. 
+Type: UInt16
+
 |===
 

doc/modules/protocol/pages/blickfeld/flow/services/flow.adoc

@@ -18,6 +18,7 @@ It is used to implement the custom storage API: https://nodered.org/docs/api/sto
 | *xref:#StoreGlobalNodes[]* | xref:blickfeld/flow/services/flow.adoc#_blickfeld_flow_services_FlowStoreGlobalNodesRequest[FlowStoreGlobalNodesRequest]| https://protobuf.dev/reference/protobuf/google.protobuf/#empty[google.protobuf.Empty]
 | *xref:#GetGlobalNodes[]* | https://protobuf.dev/reference/protobuf/google.protobuf/#empty[google.protobuf.Empty]| xref:blickfeld/flow/services/flow.adoc#_blickfeld_flow_services_FlowGetGlobalNodesResponse[FlowGetGlobalNodesResponse]
 | *xref:#WatchGlobalNodes[]* | https://protobuf.dev/reference/protobuf/google.protobuf/#empty[google.protobuf.Empty]| xref:blickfeld/flow/services/flow.adoc#_blickfeld_flow_services_FlowWatchGlobalNodesResponse[FlowWatchGlobalNodesResponse]
+| *xref:#Reload[]* | https://protobuf.dev/reference/protobuf/google.protobuf/#empty[google.protobuf.Empty]| https://protobuf.dev/reference/protobuf/google.protobuf/#empty[google.protobuf.Empty]
 |===
 [#Get]
 == Get
@@ -80,7 +81,9 @@ Flow list response
 [#Store]
 == Store
 
-Store flow
+Store flow 
+ 
+A "Reload" is required to apply the operation.
 
 [#_blickfeld_flow_services_FlowStoreRequest]
 === Request
@@ -107,7 +110,9 @@ NOTE: For node_red_json, this has to match the ID in the NodeRED JSON format.
 [#Delete]
 == Delete
 
-Delete stored flow
+Delete stored flow 
+ 
+A "Reload" is required to apply the operation.
 
 [#_blickfeld_flow_services_FlowDeleteRequest]
 === Request
@@ -168,7 +173,9 @@ Per change, a response is emitted
 [#StoreGlobalNodes]
 == StoreGlobalNodes
 
-Store global nodes
+Store global nodes 
+ 
+A "Reload" is required to apply the operation.
 
 [#_blickfeld_flow_services_FlowStoreGlobalNodesRequest]
 === Request
@@ -222,3 +229,10 @@ Flow watch global nodes response
 
 |===
 
+[#Reload]
+== Reload
+
+Reload node-red 
+ 
+This reloads all nodes from the config and restart all nodes.
+

doc/modules/protocol/pages/blickfeld/percept_pipeline/config/data_source.adoc

@@ -45,16 +45,21 @@ Configuration for retrieving point clouds from a Qb2
 3+| The fully qualified domain name of the Qb2 device. For on-device processing/configuration, 'fqdn' can be set 
 to an empty string to request the data of the current device.
 
+.2+| *port* | optional uint32| - | - 
+3+| The gRPC port of the Qb2 device. If unset the default gRPC ports 50051 (unencrypted) or 55551 (TLS) will be used.
+
 .2+| *map_from_lidar* | xref:blickfeld/base/geometry/transform.adoc[base.geometry.Transform] | - | - 
 3+| Transformation from the lidar frame to the map frame. If this transform is not set, this will be interpreted as identify 
 transformation. Transforming all point cloud topics into the map frame results in a globally consistent combined point cloud in 
 map frame.
 
 .2+| *application_key* | optional string| - | - 
-3+| Application key with authorized access level. Required if user-management is enabled on externally connected devices.
+3+| Application key with authorized access level. If set, the field serial_number has to be set as well. 
+This field is required if user-management is enabled on externally connected devices.
 
 .2+| *serial_number* | optional string| - | - 
-3+| Serial number. Required if user-management is enabled on externally connected devices.
+3+| Serial number. If set, the connection will be secured with TLS. This field is required if user-management 
+is enabled on externally connected devices.
 
 .2+| *metadata* | optional https://protobuf.dev/reference/protobuf/google.protobuf/#struct[google.protobuf.Struct] | - | - 
 3+| Arbitrary metadata storage for client applications

doc/modules/protocol/pages/blickfeld/percept_pipeline/config/zone_algorithm.adoc

@@ -100,12 +100,17 @@ Algorithm that triggers an alarm when an object of one of the selected sizes is
 3+| Selection of sizes which trigger an alarm. Each size in the array will only 
 trigger an alarm for the interval of that size.
 
-.2+| *minimum_intruder_lifetime* | uint64| - | ns 
+.2+| *minimum_intruder_lifetime* | float| - | s 
 3+| Minimum lifetime of object before alarm is triggered. 
  
 Default: 0
 
-.2+| *minimum_intruding_duration* | uint64| - | ns 
+.2+| *minimum_intruder_track_length* | float| - | m 
+3+| Minimum track length of object before alarm is triggered. 
+ 
+Default: 0
+
+.2+| *minimum_intruding_duration* | float| - | s 
 3+| Minimum active intrusion duration of object before alarm is triggered. 
  
 Default: 0

doc/modules/protocol/pages/blickfeld/percept_pipeline/data/point_cloud_type.adoc

@@ -15,5 +15,6 @@ The type of the point cloud
 | POINT_CLOUD_TYPE_FILTERED ^| 4 | Same as 'POINT_CLOUD_TYPE_FULL' but with all points excluded that are in exclusion zones
 | POINT_CLOUD_TYPE_FILTERED_FOREGROUND ^| 5 | Same as 'POINT_CLOUD_TYPE_FOREGROUND' but with all points excluded that are in exclusion zones
 | POINT_CLOUD_TYPE_BACKGROUND ^| 6 | Point cloud containing the points representing the background model/point cloud
+| POINT_CLOUD_TYPE_ANNOTATED ^| 7 | Point cloud containing a collection of points with annotation per point
 |===
 

doc/modules/protocol/pages/blickfeld/percept_pipeline/data/point_type.adoc

@@ -0,0 +1,22 @@
+[#_blickfeld_percept_pipeline_data_PointType]
+= Point Type
+
+The type of the point
+
+.Available values for blickfeld.percept_pipeline.data.PointType enum
+[cols='25h,5,~']
+|===
+| Name | Value | Description
+
+| POINT_TYPE_UNSPECIFIED ^| 0 | The point type is unspecified (default).
+| POINT_TYPE_FOREGROUND ^| 1 | The point is part of the foreground point cloud.
+| POINT_TYPE_BACKGROUND ^| 2 | The point is part of the background point cloud.
+| POINT_TYPE_FILTERED ^| 4 | The point is filtered, e.g. by applying an exclusion zone 
+or the radius outlier filter.
+| POINT_TYPE_OBJECT ^| 256 | The point is part of a detected object point cloud.
+| POINT_TYPE_OBJECT_INTRUDING ^| 512 | The point is part of a detected object point cloud which is currently 
+intruding a object based security zone.
+| POINT_TYPE_OBJECT_INTRUDER ^| 1024 | The point is part of a detected object point cloud which was previously 
+intruding a object based security zone.
+|===
+

doc/modules/protocol/pages/blickfeld/percept_processing/data/detected_object.adoc

@@ -37,6 +37,9 @@ A message representing exactly one object that is detected in the scene.
 .2+| *intruder* | xref:blickfeld/percept_processing/data/detected_object.adoc#_blickfeld_percept_processing_data_DetectedObject_Flag[Flag] | - | - 
 3+| Set when object intruded once in a security zone
 
+.2+| *velocity* | xref:blickfeld/base/geometry/vector3.adoc[base.geometry.Vector3] | - | - 
+3+| Track object velocity
+
 |===
 
 [#_blickfeld_percept_processing_data_DetectedObject_Properties]
@@ -73,6 +76,9 @@ NOTE: This is preliminary implementation and might change its behaviour signific
 3+| Set when bounding box of object is mostly located within the background / reference frame. 
 This is usually an indication for ground or vegetation detections.
 
+.2+| *track_length* | float| - | m 
+3+| The estimated track length of an object.
+
 |===
 
 [#_blickfeld_percept_processing_data_DetectedObject_Flag]

doc/modules/protocol/pages/blickfeld/percept_toolkit/services/geometry.adoc

@@ -31,6 +31,25 @@ Request for estimating alignment to ground/gravity based on imu-data and optiona
 .2+| *lidar_frame* | optional xref:blickfeld/core_processing/data/frame.adoc[core_processing.data.Frame] | - | - 
 3+| if a lidar frame is provided, it is used to estimate the z-coordinate of the translation as well.
 
+.2+| *strategy* | optional xref:blickfeld/percept_toolkit/services/geometry.adoc#_blickfeld_percept_toolkit_services_GeometryComputeGroundAlignmentRequest_Strategy[Strategy] | - | - 
+3+| Ground plane alignment estimation strategy.
+
+|===
+
+[#_blickfeld_percept_toolkit_services_GeometryComputeGroundAlignmentRequest_Strategy]
+==== Strategy
+
+Ground plane alignment strategy options.
+
+.Available values for blickfeld.percept_toolkit.services.GeometryComputeGroundAlignmentRequest.Strategy enum
+[cols='25h,5,~']
+|===
+| Name | Value | Description
+
+| STRATEGY_UNSPECIFIED ^| 0 | Unspecified. Ground plane estimation will use STRATEGY_AUTO.
+| STRATEGY_AUTO ^| 1 | Automatic mode. Ground plane alignment will use a combination of plane segmentation & accelerometer.
+| STRATEGY_PLANE_SEGMENTATION ^| 2 | Point cloud only. Use the orientation and translation computed from the plane segmentation.
+| STRATEGY_ACCELEROMETER ^| 3 | Accelerometer only. Use the orientation from the accelerometer.
 |===
 
 [#_blickfeld_percept_toolkit_services_GeometryComputeGroundAlignmentResponse]

doc/modules/protocol/pages/blickfeld/secure/config/account.adoc

@@ -17,9 +17,6 @@ authenticated.
 .2+| *access_read_only* | bool| - | - 
 3+| If true, this account has read-only access permissions.
 
-.2+| *last_login_ts* | uint64| - | - 
-3+| Last time the account was used to login as observed on system time. This is just for information purposes and might not be reliable.
-
 .2+| *failed_login_attempts* | uint32| - | - 
 3+| Counter for failed login attempts. If this value exceeds a configured threshold the account will be blocked.
 

doc/modules/protocol/pages/blickfeld/secure/config/application_key.adoc

@@ -21,8 +21,5 @@ field should help users to quickly identify different application keys but can a
 3+| If true, allow http basic access authentication using this key. 
 This option is required for ONVIF and RTSP video streaming.
 
-.2+| *last_login_ts* | uint64| - | - 
-3+| Last time the application key was used to authenticate. This is just for information purposes and might not be reliable.
-
 |===
 

doc/modules/protocol/pages/blickfeld/system/data/health.adoc

@@ -16,6 +16,9 @@ Message representing health
 .2+| *time_synchronization* | xref:blickfeld/system/data/health.adoc#_blickfeld_system_data_Health_TimeSynchronization[TimeSynchronization] | - | - 
 3+| Time synchronization status
 
+.2+| *network* | xref:blickfeld/system/data/network_status.adoc[NetworkStatus] | - | - 
+3+| Network status
+
 |===
 
 [#_blickfeld_system_data_Health_TimeSynchronization]

doc/modules/protocol/pages/blickfeld/system/data/network_status.adoc

@@ -7,25 +7,17 @@ Carries information about active connection: current statistics and network conf
 |===
 | Field | Type | Default | Unit
 
-.2+| *active_config* | xref:blickfeld/system/config/network.adoc[config.Network] | - | - 
-3+| Brings configuration information about currently active connection
-
-.2+| *statistics* | xref:blickfeld/system/data/network_status.adoc#_blickfeld_system_data_NetworkStatus_Statistics[Statistics] | - | - 
-3+| Brings statistical information about currently active connection
-
-|===
+.2+| *state* | xref:blickfeld/base/data/health.adoc#_blickfeld_base_data_Health_State[base.data.Health.State] | - | - 
+3+| High-level state of the time synchronization
 
-[#_blickfeld_system_data_NetworkStatus_Statistics]
-== Statistics
+.2+| *state_reason* | string| - | - 
+3+| Reason for given state. Is not set if state is STATE_OK.
 
-(WIP) Carries statistical information about currently active connection
-
-.Available fields in blickfeld.system.data.NetworkStatus.Statistics
-|===
-| Field | Type | Default | Unit
+.2+| *active_config* | xref:blickfeld/system/config/network.adoc[config.Network] | - | - 
+3+| Brings configuration information about currently active connection
 
-.2+| *speed* | string| - | - 
-3+| Link speed
+.2+| *link_speed* | uint32| - | MBit/s 
+3+| Link speed of network interface
 
 |===
 

protocol/blickfeld/core_processing/data/frame.proto

@@ -31,6 +31,10 @@ message Frame {
     // Unix timestamp of points.
     // Type: UInt64
     bytes timestamp = 6 [(.blickfeld.base.optional) = true, (.blickfeld.base.unit) = "ns", (.blickfeld.base.numpy_dtype) = "<u8"];
+    // Arbitrary metadata for annotation of the binary data fields.
+    // 1-dimensional array.
+    // Type: UInt16
+    bytes metadata = 100 [(.blickfeld.base.optional) = true, (.blickfeld.base.numpy_dtype) = "<u2"];
   }
   // Incremental frame ID since startup of the device.
   uint64 id = 1;

protocol/blickfeld/flow/services/flow.proto

@@ -111,8 +111,10 @@ service Flow {
     };
   }
   // Store flow
+  // A "Reload" is required to apply the operation.
   rpc Store(.blickfeld.flow.services.FlowStoreRequest) returns (.google.protobuf.Empty);
   // Delete stored flow
+  // A "Reload" is required to apply the operation.
   rpc Delete(.blickfeld.flow.services.FlowDeleteRequest) returns (.google.protobuf.Empty);
   // Watch flow changes
   rpc Watch(.blickfeld.flow.services.FlowWatchRequest) returns (stream .blickfeld.flow.services.FlowWatchResponse) {
@@ -121,6 +123,7 @@ service Flow {
     };
   }
   // Store global nodes
+  // A "Reload" is required to apply the operation.
   rpc StoreGlobalNodes(.blickfeld.flow.services.FlowStoreGlobalNodesRequest) returns (.google.protobuf.Empty);
   // Get global nodes
   rpc GetGlobalNodes(.google.protobuf.Empty) returns (.blickfeld.flow.services.FlowGetGlobalNodesResponse) {
@@ -134,5 +137,8 @@ service Flow {
       read_only: true
     };
   }
+  // Reload node-red
+  // This reloads all nodes from the config and restart all nodes.
+  rpc Reload(.google.protobuf.Empty) returns (.google.protobuf.Empty);
 }
 

protocol/blickfeld/percept_pipeline/config/data_source.proto

@@ -19,13 +19,17 @@ message DataSource {
     // The fully qualified domain name of the Qb2 device. For on-device processing/configuration, 'fqdn' can be set
     // to an empty string to request the data of the current device.
     string fqdn = 1;
+    // The gRPC port of the Qb2 device. If unset the default gRPC ports 50051 (unencrypted) or 55551 (TLS) will be used.
+    uint32 port = 5 [(.blickfeld.base.optional) = true];
     // Transformation from the lidar frame to the map frame. If this transform is not set, this will be interpreted as identify
     // transformation. Transforming all point cloud topics into the map frame results in a globally consistent combined point cloud in
     // map frame.
     .blickfeld.base.geometry.Transform map_from_lidar = 2;
-    // Application key with authorized access level. Required if user-management is enabled on externally connected devices.
+    // Application key with authorized access level. If set, the field serial_number has to be set as well.
+    // This field is required if user-management is enabled on externally connected devices.
     string application_key = 3 [(.blickfeld.base.optional) = true];
-    // Serial number. Required if user-management is enabled on externally connected devices.
+    // Serial number. If set, the connection will be secured with TLS. This field is required if user-management
+    // is enabled on externally connected devices.
     string serial_number = 4 [(.blickfeld.base.optional) = true];
     // Arbitrary metadata storage for client applications
     .google.protobuf.Struct metadata = 100 [(.blickfeld.base.optional) = true];

protocol/blickfeld/percept_pipeline/config/zone_algorithm.proto

@@ -48,13 +48,17 @@ message ZoneAlgorithm {
     repeated .blickfeld.percept_pipeline.config.ObjectSize alarm_sizes = 1;
     // Minimum lifetime of object before alarm is triggered.
     // Default: 0
-    uint64 minimum_intruder_lifetime = 2 [(.blickfeld.base.unit) = "ns"];
+    float minimum_intruder_lifetime = 6 [(.blickfeld.base.unit) = "s"];
+    // Minimum track length of object before alarm is triggered.
+    // Default: 0
+    float minimum_intruder_track_length = 7 [(.blickfeld.base.unit) = "m"];
     // Minimum active intrusion duration of object before alarm is triggered.
     // Default: 0
-    uint64 minimum_intruding_duration = 3 [(.blickfeld.base.unit) = "ns"];
+    float minimum_intruding_duration = 8 [(.blickfeld.base.unit) = "s"];
     // Trigger alarm for objects with the "in_background" property.
     // Enabling this might increase the false alarm rate.
     bool objects_in_background = 4;
+    reserved 2, 3, 5;
   }
   // Algorithm that excludes points from the input point cloud
   message Exclusion {

protocol/blickfeld/percept_pipeline/data/point_cloud_type.proto

@@ -25,5 +25,7 @@ enum PointCloudType {
   POINT_CLOUD_TYPE_FILTERED_FOREGROUND = 5;
   // Point cloud containing the points representing the background model/point cloud
   POINT_CLOUD_TYPE_BACKGROUND = 6;
+  // Point cloud containing a collection of points with annotation per point
+  POINT_CLOUD_TYPE_ANNOTATED = 7;
 }
 

protocol/blickfeld/percept_pipeline/data/point_type.proto

@@ -0,0 +1,32 @@
+// Copyright (c) 2024 Blickfeld GmbH.
+// All rights reserved.
+syntax = "proto3";
+
+import "blickfeld/base/options.proto";
+package blickfeld.percept_pipeline.data;
+
+option (.blickfeld.base.access_control_file) = {
+  level: LEVEL_AUTHORIZED
+};
+
+// The type of the point
+enum PointType {
+  // The point type is unspecified (default).
+  POINT_TYPE_UNSPECIFIED = 0;
+  // The point is part of the foreground point cloud.
+  POINT_TYPE_FOREGROUND = 1;
+  // The point is part of the background point cloud.
+  POINT_TYPE_BACKGROUND = 2;
+  // The point is filtered, e.g. by applying an exclusion zone
+  // or the radius outlier filter.
+  POINT_TYPE_FILTERED = 4;
+  // The point is part of a detected object point cloud.
+  POINT_TYPE_OBJECT = 256;
+  // The point is part of a detected object point cloud which is currently
+  // intruding a object based security zone.
+  POINT_TYPE_OBJECT_INTRUDING = 512;
+  // The point is part of a detected object point cloud which was previously
+  // intruding a object based security zone.
+  POINT_TYPE_OBJECT_INTRUDER = 1024;
+}
+