Client files for Qb2 Firmware v1.12.2 (22.01.2024)

Author: bf-jomess

doc/antora.yml

@@ -1,4 +1,4 @@
-display_version: v1.11
+display_version: v1.12
 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: v1.11
+version: v1.12

doc/modules/ROOT/assets/attachments/qb2_quick_start_manual_and_safety_information.pdf

@@ -10,8 +10,8 @@ The integrated compute module allows Blickfeld Percept software stack to run on
 
 [IMPORTANT]
 ====
-These documentation pages are a supplement to the Quick Start Manual (Blickfeld Publ. #49039) that is shipped with each unit. The instructions and safety information contained in this printed document apply at all times and take precendence over the present documentation pages.
+These documentation pages are a supplement to the xref:attachment$qb2_quick_start_manual_and_safety_information.pdf[Quick Start Manual (Blickfeld Publ. #49039)] that is shipped with each unit. The instructions and safety information contained in this printed document apply at all times and take precendence over the present documentation pages.
 User must familiarize with the safety instructions contained in the manual shipped with the device. If you have lost the document, please contact support@blickfeld.com for a digital copy.
 ====
 
-(C) Blickfeld GmbH, 2023-present
+(C) Blickfeld GmbH, 2024-present

doc/modules/ROOT/pages/index.adoc

@@ -7,10 +7,17 @@
 **** xref:developer:modules/percept/processing/index.adoc[]
 ***** xref:developer:modules/percept/processing/stream.adoc[]
 **** xref:developer:modules/percept/pipeline.adoc[]
+**** xref:developer:modules/percept/toolkit.adoc[]
+*** xref:developer:modules/push/index.adoc[]
+**** xref:developer:modules/push/push_configuration.adoc[]
 *** xref:developer:modules/flow.adoc[]
 ** Guides
 *** xref:guides:core_processing_point_cloud.adoc[]
-*** xref:guides:firmware_networking.adoc[]
+*** xref:guides:core_processing_point_cloud_o3d.adoc[]
+*** xref:guides:diagnostics_health.adoc[]
+*** xref:guides:system_firmware_update.adoc[]
+*** xref:guides:system_network_configuration.adoc[]
+*** xref:guides:system_scan_pattern.adoc[]
 ** xref:protocol:index.adoc[]
 *** blickfeld
 **** base
@@ -35,9 +42,11 @@
 ****** xref:protocol:blickfeld/beam_deflection_control/data/health.adoc[Health]
 ***** services
 ****** xref:protocol:blickfeld/beam_deflection_control/services/health.adoc[Health]
+**** config
+***** data
+****** xref:protocol:blickfeld/config/data/watch_event.adoc[Watch Event]
 **** core_processing
 ***** config
-****** xref:protocol:blickfeld/core_processing/config/demo_recording.adoc[Demo Recording]
 ****** xref:protocol:blickfeld/core_processing/config/health.adoc[Health]
 ****** xref:protocol:blickfeld/core_processing/config/point_cloud.adoc[Point Cloud]
 ***** data
@@ -68,7 +77,6 @@
 ****** xref:protocol:blickfeld/diagnostics/services/log.adoc[Log]
 ****** xref:protocol:blickfeld/diagnostics/services/report.adoc[Report]
 ****** xref:protocol:blickfeld/diagnostics/services/self_test.adoc[Self Test]
-***** xref:protocol:blickfeld/diagnostics/options.adoc[Options]
 **** flow
 ***** config
 ****** xref:protocol:blickfeld/flow/config/flow.adoc[Flow]
@@ -139,6 +147,20 @@
 ****** xref:protocol:blickfeld/push/services/destination.adoc[Destination]
 ****** xref:protocol:blickfeld/push/services/health.adoc[Health]
 ****** xref:protocol:blickfeld/push/services/push.adoc[Push]
+**** secure
+***** config
+****** xref:protocol:blickfeld/secure/config/account.adoc[Account]
+****** xref:protocol:blickfeld/secure/config/application_key.adoc[Application Key]
+****** xref:protocol:blickfeld/secure/config/certificate.adoc[Certificate]
+****** xref:protocol:blickfeld/secure/config/device_credentials.adoc[Device Credentials]
+****** xref:protocol:blickfeld/secure/config/private_key.adoc[Private Key]
+****** xref:protocol:blickfeld/secure/config/public_key.adoc[Public Key]
+***** services
+****** xref:protocol:blickfeld/secure/services/account.adoc[Account]
+****** xref:protocol:blickfeld/secure/services/application_key.adoc[Application Key]
+****** xref:protocol:blickfeld/secure/services/authentication.adoc[Authentication]
+****** xref:protocol:blickfeld/secure/services/device_credentials.adoc[Device Credentials]
+****** xref:protocol:blickfeld/secure/services/session.adoc[Session]
 **** system
 ***** config
 ****** xref:protocol:blickfeld/system/config/device.adoc[Device]

doc/modules/developer/images/architecture.svg

@@ -21,47 +21,45 @@ $ pip3 install blickfeld_qb2
 ----
 
 == Connecting to Qb2 
-To interact with a Qb2 device, a gRPC connection has to be established. For that we use the gRPC ```Channel``` from the ```blickfeld_qb2``` library.
-An IP address or a hostname of a Qb2 device can be used to establish a connection. The connection is by default encrypted and authenticated. 
+To interact with a Qb2 device, a gRPC connection must be established. For this purpose, the gRPC ```Channel``` from the ```blickfeld_qb2``` library is used.
+Either the IP address or the hostname of the Qb2 device can be used to establish a connection. The connection is encrypted and authenticated by default. 
 
-.Simple example which imports the blickfeld_qb2 python library and creates communication channel to a Qb2
+.Simple example which imports the blickfeld_qb2 python library and creates a communication channel to Qb2
 [source,python]
 ----
 import blickfeld_qb2
-# open secure connection to Qb2
+# Open a secure connection to Qb2
 with blickfeld_qb2.Channel(fqdn_or_ip="qb2-xxxxxxxxx") as channel:
     # Call methods of services
     # ..
 ----
 
-NOTE: The ```serial_number``` can be passed additionally to authenticate a particular device. If it is not supplied, the authentication only checks if it is a Blickfeld device.
+NOTE: The ```serial_number``` can be passed additionally to authenticate a particular device. If not supplied, the authentication only checks if it is a Blickfeld device.
 
 == Simple API Requests
 
-The code snippet below shows an example of connecting to Qb2 with a hostname ```qb2-xxxxxxxxx``` and fetching information about its firmware version. 
-For that we use the ```Firmware``` service from ```blickfeld_qb2.system.services``` namespace over the gRPC channel and make a 
-request ```get_status()``` to get a response with information about the currently installed firmware. 
+The code snippet below provides an example of connecting to Qb2 with the hostname ```qb2-xxxxxxxxx``` and retrieving information about its firmware version. 
+In this case, the ```Firmware``` service from ```blickfeld_qb2.system.services``` namespace is used over the gRPC channel making a request ```get_status()``` to receive a response containing information about the currently installed firmware. 
 
 [source,python]
 ----
 import blickfeld_qb2
 
-# open secure connection to Qb2
+# Open a secure connection to Qb2
 with blickfeld_qb2.Channel(fqdn_or_ip="qb2-xxxxxxxxx") as channel:
-    # request firmware status 
+    # Request the firmware status 
     response = blickfeld_qb2.system.services.Firmware(channel).get_status()
-    # extract firmware version 
+    # Extract the firmware version 
     firmware_version = response.status.installed_firmware_info
-    # print firmware version
+    # Print the firmware version
     print(firmware_version)
 
     # NOTE: A channel can be reused for other requests. It is not required to create a channel per request.
 ----
 
-Every response to the service call is an object that usually consists of several nested objects according to the protocol schema defined in the corresponding sections of the documentation. In this scenario we can get information about firmware version installed via the
-field ```response.status.installed_firmware_info```. 
+Every response to the service call is an object that typically comprises several nested objects following the protocol schema defined in the corresponding sections of the documentation. In this scenario, the information about the installed firmware version can be obtained via the field ```response.status.installed_firmware_info```. 
 
-The output of the print should look similar to the one shown below: 
+The print output should resemble the example shown below: 
 
 [source,bash]
 ----
@@ -70,21 +68,21 @@ FirmwareInfo(label='JAKOB v1.5.0', version=Version(major=1, minor=5, revision='e
 
 == Asynchronous Requests
 
-If needed, the Blickfeld library can be also used in a fully asynchronous mode. In the example shown below we introduce a coroutine ```get_firmware_version()```, which opens an asynchronous gRPC channel and makes use of an asynchronous request ```async_get_status()``` to get the same information about the Qb2 firmware status.
+If necessary, the Blickfeld library can also be used in a fully asynchronous mode. In the example shown below we introduce a coroutine ```get_firmware_version()```, which opens an asynchronous gRPC channel and utilizes an asynchronous request ```async_get_status()``` to obtain the same information about the Qb2 firmware status.
 
 [source,python]
 ----
 import asyncio
 import blickfeld_qb2
 
 async def main():
-    # open secure asynchronous connection to Qb2
+    # Open a secure asynchronous connection to Qb2
     async with blickfeld_qb2.Channel(fqdn_or_ip="qb2-xxxxxxxxx") as channel:
-        # request firmware status asynchronously and await for the response 
+        # Request the firmware status asynchronously and await for the response 
         response = await blickfeld_qb2.system.services.Firmware(channel).async_get_status()
-        # get firmware version from the response 
+        # Get the firmware version from the response 
         firmware_version = response.status.installed_firmware_info
-        # print firmware version
+        # Print the firmware version
         print(firmware_version)
 
         # NOTE: A channel can be reused for other requests. It is not required to create a channel per request.
@@ -96,9 +94,9 @@ asyncio.run(main())
 
 NOTE: To make an asynchronous request over the asynchronous channel, the desired method name should be prefixed with ```async_```. 
 
-This coroutine can be further executed on the event loop. The output of the print should look similar to the one shown below:  
+This coroutine can be further executed on the event loop. The print output resemble the example shown below:  
 
 [source,bash]
 ----
 FirmwareInfo(label='JAKOB v1.5.0', version=Version(major=1, minor=5, revision='e87dfda0', is_release=True), allowed_downgrade_version=Version(minor=26))
-----
+----

doc/modules/developer/nav.adoc

@@ -1,29 +1,29 @@
-= Flow (BETA)
+= Blickfeld Flow (BETA)
 
-CAUTION: This feature is currently in the testing phase and not yet completed. Changes in upcoming firmware releases may cause behaviourals and APIs created with Flow to break.
+CAUTION: This feature is currently in the testing phase and not yet completed. Changes in upcoming firmware releases may cause behaviours and APIs created with Flow to break.
 
-Blickfeld Flow is a low-code prototyping and integration tool for customizing and extending the functionality of a Qb2 sensor.
+Blickfeld Flow is a low-code prototyping and integration tool for customizing and extending the functionality of the Qb2 sensor.
 It is based on the open-source tool https://nodered.org[Node-Red], an efficient and state-of-the-art flow-based programming tool for event-driven applications.
-It is seamlessly integrated in the Blickfeld sensor while maintaining the flexibility and the https://flows.nodered.org/[library] provided by the open source community.
+The tool is seamlessly integrated in the Blickfeld sensor while maintaining the flexibility and the https://flows.nodered.org/[library] provided by the open-source community.
 
-== Key Features
+== Key features
 
 * Simple access to the Blickfeld Qb2 API through built-in nodes
 * Browser-based wiring and editing of flows with the WebGUI
 * Support for various input and output interfaces such as REST, Websocket, MQTT, Kafka, ..
 * Live deployment of changes with status and debug messages
-* Deployment of custom Javscript methods
+* Deployment of custom Javascript methods
 * Import, export and library support to re-use flows
-* Fully integrated and on-device execution (the flows can be configured to start automatically with the power-up of the Qb2)
+* Fully integrated and on-device execution (flows can be configured to start automatically with the power-up of Qb2)
 
 == How to get started?
 
-NOTE: Ensure that the Qb2 sensor is running a firmware version that is at least v1.8 or higher. If it is not, please proceed to download the most recent release from https://github.com/Blickfeld/blickfeld-qb2/releases[Github] and then upload it to the sensor using the firmware page.
+NOTE: Ensure that the sensor is running the firmware version v1.8 or higher. If it is not, please proceed to download the most recent release from https://github.com/Blickfeld/blickfeld-qb2/releases[Github] and then upload it to the sensor using the firmware page.
 
 Blickfeld Flow is available in the WebGUI under Configuration / Flow.
-With Blickfeld Flow, users have the ability to generate new flows by simply dragging nodes into the workspace and establishing connections between them.
+With Blickfeld Flow, users can generate new flows by simply dragging nodes into the workspace and establishing connections between them.
 
-Overall, it is highly recommended to follow the https://nodered.org/docs/[Node-Red documentation] with its https://nodered.org/docs/tutorials/first-flow[tutorials].
+Overall, it is highly recommended to follow the https://nodered.org/docs/[Node-Red documentation] and its https://nodered.org/docs/tutorials/first-flow[tutorials].
 
 == Qb2 API access
 
@@ -36,32 +36,32 @@ Additionally, built-in flows are available for reference.
 
 == Limitations
 
-=== Compute Power
+=== Compute power
 
-The Qb2 devices leverage a quad-core ARM Cortex-A72 processor for on-device processing tasks.
+Qb2 devices leverage a quad-core ARM Cortex-A72 processor for on-device processing tasks.
 Only a fraction of this computational capacity is allocated to Blickfeld flows.
 Consequently, resource-intensive flows might exhibit reduced performance.
 It is worth highlighting that this adjustment does not significantly impact the fundamental operations of the core device. This is because Blickfeld Flows are executed with a lower process priority, ensuring the stability of core device functionalities.
 
-Simple recommended optimizations:
+Here are some simple recommended optimizations:
 
 * https://cookbook.nodered.org/basic/rate-limit-messages[Slow down messages passing through a flow]
 * Dive into https://nodered.org/docs/user-guide/messages[Message Guides] to understand the potential compute & memory impact
 
-=== Point Cloud Processing
+=== Point cloud processing
 
-At the moment, it is not recommended to process point clouds with Blickfeld flows.
+At the moment, processing point clouds with Blickfeld flows is not recommended.
 It's a resource-intensive operation that usually requires optimizations to run in real-time.
 
 Please approach the Blickfeld Support with the corresponding use-case where point cloud processing is required.
-We can probably provide a suitable solution.
+We can likely provide a suitable solution.
 
 === Storage
 
-The custom packages are installed on a 2GB large data partition.
+Custom packages are installed on a 2GB large data partition.
 Depending on the dependencies, the storage limit may be reached.
 
 === Maintainability of complex flows
 
-Even though it is very easy to get started with Blickfeld Flows, large and complex flows can lead to higher maintainability efforts in the future.
+Even though it is straightforward to get started with Blickfeld Flow, large and complex flows can lead to higher maintainability efforts in the future.
 It is highly recommended to carefully read through the https://nodered.org/docs/developing-flows/[Developing Flows] guide of Node-Red.

doc/modules/developer/pages/client_libraries/python.adoc

@@ -44,7 +44,7 @@ The xref:protocol:blickfeld/percept_processing/services/pipeline.adoc[Pipeline s
 
 === Data Retrieval
 
-The xref:protocol:blickfeld/percept_processing/services/point_cloud.adoc[Point Cloud] and 
+The xref:protocol:blickfeld/percept_processing/services/point_cloud.adoc[Point Cloud], 
 xref:protocol:blickfeld/percept_processing/services/states.adoc[States] and 
 xref:protocol:blickfeld/percept_processing/services/volume_map.adoc[Volume Map] 
 services enable the client to retrieve data of the corresponding types. You can find more information about this in the 

doc/modules/developer/pages/modules/flow.adoc

@@ -0,0 +1,24 @@
+= Blickfeld Percept Toolkit
+
+The Blickfeld Percept Toolkit module provides a gRPC interface to perform on-demand geometric processing tasks.
+
+== Services
+
+Blickfeld Percept Toolkit provides the following services:
+
+* Geometry
+* Health
+
+=== Geometry
+
+This service offers the capability to perform on-demand computations, including:
+
+
+* Ground alignment: Aligning a point cloud with the ground plane.
+* Registration refinement: Improving the registration of a set of point clouds by refining their transformations.
+
+See xref:protocol:blickfeld/percept_toolkit/services/geometry.adoc[the service definition] for more information.
+
+=== Health
+
+The xref:protocol:blickfeld/percept_toolkit/services/health.adoc[Health service] can be utilized to obtain or stream information regarding the current status of the module itself.

doc/modules/developer/pages/modules/percept/processing/index.adoc

@@ -0,0 +1,44 @@
+= Blickfeld Percept Push
+
+The Blickfeld Push module provides a gRPC interface for subscribing to streams from the  xref:developer:modules/percept/processing/index.adoc[Blickfeld Percept Processing] service and "pushing" the data to a desired destination.
+
+== Architecture
+
+The following image shows an overview of the Blickfeld Push data flow architecture.
+
+image::architecture.svg[Blickfeld Push Data Flow Architecture]
+
+
+* Blickfeld Percept Processing gRPC Client
++
+The Blickfeld Push module acts as a client to xref:developer:modules/percept/processing/index.adoc[Blickfeld Percept Processing] to access data streams and push it to configured destinations.
+
+* Push API gRPC Server
++
+To serve its own API, the module runs a gRPC server that manages all API calls defined in the xref:protocol:blickfeld/push/services/push.adoc[Push] service.
+
+[NOTE]
+====
+For further details on various push configurations, you can refer to the: xref:developer:modules/push/push_configuration.adoc[Push Configuration Overview]
+====
+
+== Services
+
+Blickfeld Push offers the following services:
+
+* Push
+* Destination
+* Health
+
+=== Push
+
+Provides services for storing, deleting, enabling, and disabling one or multiple push configurations. When a push configuration is enabled, Blickfeld Push will automatically publish the data stream provided by Blickfeld Percept Processing to the configured destination.
+See xref:protocol:blickfeld/push/services/push.adoc[Push] for the service definition.
+
+=== Destination
+
+A service to validate the push configuration, e.g. if the destination is correct, see xref:protocol:blickfeld/push/services/destination.adoc[Destination].
+
+=== Health
+
+The xref:protocol:blickfeld/push/services/health.adoc[Health service] can be used to obtain or stream information regarding the current status of the push configurations and the module itself.