HPD Studio User Guide Shield#

Abstract#

The Novelda UWB sensor demo kit enables the evaluation of Novelda´s UWB sensor products. The demo kit contains a X4F103 Shield that is designed to work with the Nordic nRF52840DK evaluation board. The X4F103 is a 12x12mm sensor module with a wide field-of-view that can be used for both occupancy and proximity use cases. The SW examples are written to work out of the box on the Nordic nRF52840. Since Nordic follows the Arduino pin-out the X4F103 Shield is compatible with any other development board following this standard as long as voltage is limited to maximum 3.3 V. The sensor output can be visualized in the Novelda HPD Studio application for Windows/macOS and there is a command line option available for long-term logging and prototyping. The SW can run also run on Raspberry Pi 3/4.

Brief Step-by-Step Procedure#

This section briefly outlines the steps to set up and run the Novelda UWB sensor demo. More details are found in the sections below.

  1. Run the Novelda HPD Studio Windows installer.

    1. The installer will automatically install Novelda HPD Studio as well as the required drivers.

    2. For other operating systems see more detailed sections further down.

  2. Connect the X4F103 Shield to the Nordic or Arduino board.

  3. Attach the sensor module to a suitable location.

    1. For occupancy / light control the sensor must be placed in the ceiling or inside a ceiling-mounted light fixture.

    2. For proximity applications, the sensor must be placed vertically on the wall or on the product the sensor is intended for.

    3. Keep in mind that the radar antenna must point towards the detection zone.

  4. Run the demo application by double-clicking the Novelda HPD Studio shortcut on the desktop. Settings like product, range, sensitivity and timeout can be selected in the application.

How To Connect The X4F103 Shield#

The X4F103 Shield is connected to the Nordic nRF52840 board as described in the following table and picture (add later).

Pin X4F103 Shield

GPIO Nordic Board

Pin Description

VIN

VDD

Input voltage

GND

GND

Ground

SCL

P0.27

I2C Serial Clock

SDA

P0.26

I2C Serial Data

SCLK

P1.15

SPI Serial Clock

POCI

P1.14

SPI: Peripheral Out, Controller In

PICO

P1.13

SPI: Peripheral In, Controller Out

CS0

P1.12

SPI Chip Select

EN

P1.11

Enable

IRQ

P1.10

Interrupt
../_images/shield1.png

Novelda HPD Studio - PC Application#

Windows Installation procedure#

  • Run Novelda HPD studio installer.

  • The following window from Microsoft Defender SmartScreen will appear. To continue the installation, press “More info” and then “Run anyway”.

../_images/install1.png ../_images/install2.png

  • Follow the instructions from the installer. In the first window, the user can choose to install additional FTDI Drivers. This is necessary to run the demo. The FTDI installer window will appear after the installation of the Novelda HPD Studio application has been completed. If the user already has FTDI drivers on their computer, this box can be unchecked.

MacOS Installation Procedure#

  • Download and extract the installation zip file.

  • Open the folder in the terminal.

  • Run xattr -d com.apple.quarantine Novelda\ HPD\ Studio.app

  • Change permissions using chmod -R 755 "Novelda HPD Studio.app"

Note

Currently super user permissions are required to run Novelda HPD Studio. Use the following command to run the application:
NoveldaHPDStudio_x64-osx % sudo Novelda\ HPD\ Studio.app/Contents/MacOS/Novelda\ HPD\ Studio
Double clicking the icon will start the application, but will eventually give you an error message.

Raspberry Pi Installation Procedure#

  • Download and extract the installation zip file (in the terminal using tar –xvzf Novelda HPD Studio-$version-linux-armhf.tar.gz).

  • Open the folder in the terminal

  • Enable I2C (Menu → Preferences → Raspberry Pi Configuration → Interfaces)

  • Change permissions using sudo chmod +x "NoveldaHPDStudio-armhf.AppImage"

  • Run the application by sudo ./NoveldaHPDStudio-armhf.AppImage

Note

The application works on the 32 bits version of Raspberry Pi OS with desktop based on Debian 11 Bullseye

How to run the application#

The program communicates with the connected sensor through USB. When the program is launched, the user will have to select some settings to get started.

Select the product#

Choose the product to evaluate. The available algorithms and the version will be listed when the GUI is started. The demo currently supports algorithms for the following products:

  • Occupancy sensor - ceiling mounted, typically used for controlling luminaires.

  • Proximity sensor - vertically mounted, typically inside products such as appliances to control displays or similar.

  • Proximity-Outdoor sensor - For appliance interaction. Using a vertically mounted sensor. Tuned for rain rejection.

Select the connected sensor#

The user should select the correct sensor from the menu with available sensors.

Select range, sensitivity and timeout#

  • The user selects a maximum detection range from the drop-down menu. The maximum distance will vary based on which algorithm is being used.

    • Keep in mind that the sensor can see through most walls and that static objects can act as mirrors. It is a good idea to set the max range as short as possible to avoid false detections and allow a more free choice of sensitivity settings in the next step.

Note

Within the selected detection range all movements will be detected.
Right outside the detection zone there is a transition area of approximately 20 cm. Within this area there is a decreasing probability of detection. This is due to the pulse width of the radar signal.
Outside this transition zone, there is an absolute rejection of any movements.
The transition zone is illustrated in the figure below.

  • Sensitivity and timeout

    • All the algorithms offer a selection of sensitivity settings (usually 1-5). These must be chosen carefully to balance the desired detection probability against the probability of false triggers from unwanted targets in the zone.
      The optimal setting depends on the environment of the sensor (the amount of clutter in the detection zone) and the application-specific consequences of missed detections and false triggers.
      Key points to bear in mind are that a longer hold time allows the choice of a less sensitive setting, which in turn will reduce the number of false detections.

    • The timeout decides how long the sensor reports “DETECTION” after the last actual detection. The current signal processing algorithms rely on a certain hold time for robust operation. This hold time is user-configurable within a given range for each algorithm, but Novelda recommends using at least the following:

      • Occupancy: 60 seconds

      • Proximity: 15 seconds

  • Start

    When the correct settings are selected, press the “Start” button.

  • Change Settings

    It is possible to go back to change the settings at any time.

When the program starts, a new page will show the sensor output and the history. The current state (detection/no detection), the timeout countdown and the selected settings are visible at the top of the page. The first plot shows the logic history with the detections (+timeout) marked in green. The sensor history is plotted below and shows each detection made. How easy it is to trigger a detection will be affected by the chosen sensitivity.

Power vs. Range plot#

A power vs. range plot can be activated in the settings menu in the top right corner. When this box is checked the following plot will show up under the existing plots. The bright, green line displays the signal power at different ranges, and the darker, blue line shows the detection threshold.

Command Line Interface (CLI)#

The Novelda HPD Studio also has a command line interface which will print the sensor data to the standard output in a semicolon-separated format. The format of the output is: timestamp; distance (currently not available); presence (0/1); The CLI includes the same options for range, sensitivity and timeout as in the GUI. To print all options for CLI run the “Novelda HPD Studio.exe” (“NoveldaHPDStudio-armhf.AppImage” for RPi) followed by -h or - -help in the command line.

& '.\Novelda HPD Stuido.exe' -h

../_images/CLI-h.png

To run with default settings, run the “Novelda HPD Studio.exe” followed by -s, -n, the wanted algorithm and the connected sensor & '.\Novelda HPD Studio.exe' -n -s "Algortihm Version" X4F103, as shown in the next figure. The supported algorithms are listed at the bottom of the page when the help page is printed, as shown in the previous figure.

../_images/CLI-default.png

The settings can be adjusted by adding the timeout (-t), range and sensitivity manually. To print the options for range and sensitivity, the following format is used: & '.\Novelda HPD Studio.exe' [algorithm] <module> [parameter] -h. (Example: & .\Novelda HPD Studio.exe "Occupancy 0.3.14" X4F103 range -h) An example of how to run the program with other settings is shown in the figure below.

../_images/CLI-extraSettings.png

The –print-options command helps list all the algorithms, snesors, sensitivity and range options available on HPDStudio like shown in the image below. "Novelda HPD Studio.exe" --print-options

../_images/print_options.png

The –stop-after option provides the possibility to stop the console output after a desired duration in milliseconds. For example: "Novelda HPD Studio.exe" <"Algorithm"> X4F103   sensitivity <>  range <> --stop-after <> -s -n

../_images/stop_option.png

macOS Instructions#

To run from CLI on macOS you have to navigate to the actual executable file inside the .app package. The command call to run HPD Studio is: NoveldaHPDStudio_x64-osx % sudo Novelda\ HPD\ Studio.app/Contents/MacOS/"Novelda HPD Studio"

Adding new .hpd files#

If a new version of the algorithm is available, users can easily add this to their existing Novelda HPD Studio application. The algorithm will be provided as a .hpd file which should be added to the algorithms folder, as shown in the next image.

../_images/hpd-files.png

Novelda HPD Studio also supports drag-and-drop of .hpd files. This means that the user can drag .hpd-files directly from the download folder and into the application, see the next picture. The new algorithm should appear immediately in Novelda HPD Studio, and in the algorithms folder.

../_images/drag-and-drop.png

If double-clicking a .hpd-file, Novelda HPD Studio will open with this specific algorithm. This will however not add the file to the correct folder, and the algorithm will not be there the next time the user opens HPD Studio in the normal way.

Customizable Python Demos#

Novelda HPD Studio supports streaming sensor data to a temporary buffer. This functionality can be used to write custom application logic on top of, or in place of, the standard application logic in HPD studio (which is a simple timer). To use this functionality, the “Stream data over named pipe/FIFO” box can be checked under the settings menu in the HPD Studio application. It can also be activated via the Command Line Interface with the following argument -p (it is still possible to select and change options via the Graphical User Interface (GUI) if that is desired). In PowerShell, the full command looks like this, assuming you have navigated to the install/bin directory: & '.\Novelda HPD Studio.exe' -p

If your application does not require visual output, you may want to specify the -n/--no-gui flag to start streaming data without having to select options via the GUI. When using the -n flag, it is necessary to explicitly specify which algorithm you want to run, and which sensor you are using. All other options will use the default value unless explicitly specified. Minimalistic example in PowerShell: & '.\Novelda HPD Studio.exe' "Occupancy 0.3.14" X4F103 -n -p

For more details, please refer to the section titled “Command Line Interface (CLI)”.

Picking up streamed data in Python#

Once Novelda HPD Studio is running, and streaming data to a buffer, the data can be picked up by another program. Novelda provides a collection of python scripts for quickly getting started with reading this data. These scripts can be found in the zipped folder “NoveldaPythonDemo.zip” which is located on: X4 Demo Kit webpage

First time use#

Before first-time using the Python scripts, it’s important to install all dependencies. First and foremost, you will need to install Python 3 and add the location of this installation to your PATH environment variable. Open a terminal window, like PowerShell, and navigate to the “NoveldaPythonDemo” folder. Execute the following commands to install the required python packages: python -m pip install novelda_serialization-0.1.1-py3-none-any.whl python -m pip install -r requirements.txt

Running Examples#

There are two examples of getting started with reading streamed data in Python. Run the command python NAME_OF_EXAMPLE to run the wanted example from the “NoveldaPythonDemo” folder. The script called ex1_basic_app_logic.py is the most minimalistic example. It shows how to read which settings Novelda HPD Studio is currently using, including where to find the data buffer, and how to attach a callback function to this data stream so that you can write your own application logic. The callback function is called each time the result of a new radar frame is added to the buffer.

The script called ex2_basic_app_logic_with_holdtime.py is slightly more advanced and expands on example 1 by adding a state machine to keep track of a variable timer. This timer is used to add a hold time to the sensor data, which is useful in applications where the sensor is waking up another system. For Novelda’s OccupancyMinimal and ProximityMinimal software products, it is recommended to always use a hold time for best performance (minimum recommended hold time differs between products). The hold time can be specified when starting Novelda HPD Studio - either in the GUI or by using the -t option in the CLI.

Troubleshooting#

When starting up the Novelda HPD Studio application, an error message like the one below can be displayed if there is something that doesn’t work as expected. To troubleshoot this, please start the application from the command line using the -l7 parameter: .\Novelda HPD Studio.exe "Algorithm" -l7 The printed output will show a more detailed error message that can be debugged in collaboration with Novelda.

References#

[1] X4 Demo Kit webpage

[2] NEMA Standard WD 7-2011 (R2016)