x, y , z
INFRASTRUCTURE
GPS-LIKE POSITIONINGSINGLE SELF-POSITIONING
x, y , z
x, y , z
AN5623
Application note
Visualizing of 3D modes in BeSpoon location client tool
Introduction
BeSpoon location client (BspLocClient) is conceived as a server frontend for BeSpoon real‑time location system (RTLS), for
example, to visualize the position of a device on a 2D map in real‑time and to record positions. Basic features such as tracking
visualization, record, replay, are available on Windows® and Ubuntu®, with or without a server. Advanced features such as
Viewer 1D, Calibration 2D, Debug 2D, UWB Stats, Server Stats, and LOS indicator are available on Ubuntu® only and require a
server.
If you already use BeSpoon RTLS, BspLocClient is installed on the server PC. If you use B-UWB-MEK1 hardware only,
installation files are included in the SDK, in tools > exe for Windows®, and tools > deb for Ubuntu®. In the application
note, BspLocClient is used without any server connection, in two device-centric tracking modes: 3D Single Self-Positioning or
3D GPS‑like positioning, as illustrated in Figure 1.
This application note complements the information available in the SDK. It is intended for advanced users already familiar with
3D-single self-positioning mode in the quick start guide and 3D GPS‑like positioning mode in the 3D GPS
BeSpoon RTLS application note. The procedures are done with Terminal, BspLocClient, BeSpoon MOD1/MEK1 programming
tool, and BeSpoon location server WebUI applications.
The documentation is based on system version 3.x.
‑
like positioning within
Figure 1. Visualization of 3D modes in BspLocClient
AN5623 - Rev 1 - April 2021
For further information contact your local STMicroelectronics sales office.
www.st.com
1 General information
B-UWB-MEK1 embeds the B-UWB-MOD1, which features the STM32L476JE 32-bit microcontroller based on the
Arm® 32-bit Cortex®‑M4 processor.
Note: Arm is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or elsewhere.
Definitions
Table 1 presents the definition of acronyms that are relevant for a better understanding of this document.
Table 1. List of acronyms
Term Definition
3D_SELF 3D single self-positioning
BLR Beacon-listening rate
HF Hyperframe
PHS Protocol hyperframe size
PSN Protocol slot number
PSS Protocol slot size
RTLS Real‑time locating system
RV Rendez-vous (slot and zone)
SF Superframe
SFI Superframe information
TDMA Time-division multiple access
UWB Ultra-wideband
AN5623
General information
References
Refer to the following documents for an introduction to the B-UWB-MEK1 and B-UWB-MOD1 products in indoor
location systems:
• Ultra-wideband module for high-precision indoor location (DB4404)
• Evaluation kit for the B-UWB-MOD1 ultra-wideband module (DB4392)
• B-UWB-MEK1 quick start guide (UM2798)
• SDK advanced documentation
Demonstration software
Contact the local STMicroelectronics sales office or distributor (refer to www.st.com) for the latest software and
associated documentation.
AN5623 - Rev 1
page 2/20
2 Install BspLocClient
On Windows®, the application can be started directly from the .exe file. In the SDK package, just open tools >
exe and click on bsplocclient_basic_X. XX.X_amd64.exe to start BspLocClient.
On Ubuntu® (not needed if BeSpoon RTLS server is installed on the PC, as the client application is part of the
server package):
Step 1. Search [Terminal] by typing "Terminal" in the Ubuntu® search tool.
The application icons can be dragged and dropped to the left menu bar for quick access.
Figure 2. Dragged and dropped application icons to the left menu bar for quick access
AN5623
Install BspLocClient
AN5623 - Rev 1
Step 2. Open [Terminal].
Step 3. Ensure the computer is connected to the Internet, to ensure the automatic download of the execution
applications Qt packages from the Linux® software repository.
Step 4. Enter the following command (installing Qtx.x.x packages):
sudo apt-get install qt5-default libqt5svg5 libqt5serialport5
libqwt-qt5-6
The programming tool displays a progress bar and device information.
Step 5. Check if a previous version is installed:
– No previous version installed: skip to step 6.
– Previous version installed:
a. Save the old client configuration files.
b. Uninstall previous packages with the following command:
sudo dpkg –-purge bsplocclient libbsptransport bsploclibrary
page 3/20
AN5623
Install BspLocClient
Step 6. Access the deb directory in the SDK by using the Linux® command cd ("change directory") and
entering the corresponding path.
In the example below, the user is navigating from the home directory and the SDK directory is stored
on the desktop:
cd Desktop/mod1_SDK_3.x.x_REVISION/tools/deb
Step 7. Install the BspLocClient with the following command:
sudo dpkg -i *.deb
Step 8. To check the installation, start typing “bsp” or "BeSpoon" in the search tool.
It displays an icon labeled as "BeSpoon Location Viewer".
Figure 3. BeSpoon Location Viewer icon
AN5623 - Rev 1
page 4/20
3 Configure the topology (optional)
Note: Skip this section if you want to visualize the mobile device only.
BspLocClient can display the mobile device together with the fixed devices used to track it:
• Fixed MEK1 boards in 3D single self-positioning
• Anchors in 3D GPS‑like positioning within a BeSpoon RTLS.
To take this topology into account, the application needs a file named base_position.ini.
The following procedure shows how to create this file and import it into BspLocClient.
Step 1. Retrieve the topology:
– 3D_SELF: In MOD1/MEK programming tool > Localization > INFRA, select [Export To
Ini].
– 3D_GPS: In BeSpoon Loc Server WebUI > DEVICES > Devices management, click on
[Export devices].
Step 2. Get the file path.
Step 3. Rename the file base_position.ini and move it into the right system administration directory (/et
c/BeSpoon) . On Ubuntu®, use the following command:
AN5623
Configure the topology (optional)
sudo mv FILEPATH /etc/BeSpoon/base_position.ini
AN5623 - Rev 1
page 5/20
4 Set BspLocClient for MEK positioning
On Windows®, the application directly starts with preferences adapted to MEK1 positioning, as shown in Figure 4.
Figure 4. Application preferences adapted to MEK positioning
AN5623
Set BspLocClient for MEK positioning
On Ubuntu®:
Step 1. Open BspLocClient.
Step 2. In the start window, select [Local File].
Step 3. As the application doesn't find any connection to a BeSpoon RTLS server, it asks to confirm that
BspLocClient is used without a server.
Figure 5. Use of BspLocClient without server connection
Click on [Yes]
The application first opens as a standard interface for BeSpoon RTLS use.
Step 4. In the main menu, select [Tools > Preferences].
AN5623 - Rev 1
page 6/20
Set BspLocClient for MEK positioning
Step 5. In the Preferences window, select [MEK positioning] and confirm by clicking on [OK].
Figure 6. MEK positioning choice in the Preferences menu
AN5623
Step 6. Close and re-open BspLocClient.
AN5623 - Rev 1
page 7/20
5 Configuring the map
Step 1. In the [Tools > Preferences] window, open the [Graph] tab.
Step 2. Set the visualization options:
a. Upload a floor plan image by clicking on the [Browse] button Formats allowed: .bmp, .gif, .jp
g, .jpeg, or .png.
b. Specify the offset and the scale on X and Y axes, as shown in Figure 7.
AN5623
Configuring the map
Figure 7. Specify the offset and the scale on X and Y axes
AN5623 - Rev 1
c. Confirm by clicking on [OK].
d. Restart BspLocClient.
The displayed information depends on the choice in Section 3 :
– No topology imported:
◦ [Devices info > Anchors] is empty.
◦ The [Viewer 2D] tab displays the floor plan only.
– Topology imported (base_position.ini file loaded):
◦ [Devices info > Anchors] displays the ID of the fixed devices (MEK1 boards or anchors).
◦ The [Viewer 2D] tab displays purple anchor icons with the ID of the fixed devices on the
floor plan.
page 8/20
6 Start tracking
Step 1. Connect the mobile board to the computer.
Step 2. Open BspLocClient.
Step 3. As described in Section 5 , select [Local File] at the start and confirm that the application is used
without server connection as shown in Figure 7.
AN5623
Start tracking
Figure 8. Request to continue without server connection
AN5623 - Rev 1
page 9/20
AN5623
Start tracking
Step 4. In the [MEK Positioning] tab, select the USB port if several ones are available and click on [Start
MEK positioning].
Figure 9. USB port selection and MEK positioning start
The ID of the mobile device appears in [Devices info > Tags].
Figure 10. Devices info display
AN5623 - Rev 1
page 10/20
Step 5. Switch to [Viewer 2D] for visualization.
Figure 11. Viewer 2D vizualization
AN5623
Start tracking
AN5623 - Rev 1
page 11/20
AN5623
Start tracking
Step 6. Customize the information on the map using [View] in the main menu. The 3D-single self-positioning
mode and the 3D GPS‑like positioning mode are compatible with the options listed below.
– [View Anchors] (Keyboard shortcut: a): Anchor icon and ID of the fixed devices. To activate it,
close and re-open the application.
Figure 12. View Anchors
– [View Label] (Keyboard shortcut: l (lowercase L)): Device ID of the mobile device
Figure 13. View Label
– [Trace] (Keyboard shortcut: t): Trace of the mobile device. Adjustments: dots/line displaying, three
pre-set lengths, and customizable width
Figure 14. Trace
– [View elevation] (Keyboard shortcut: e): Real-time position of the mobile device on the z‑axis
Figure 15. View elevation
– [View coordinates] (Keyboard shortcut: k): Real-time x, y, and z coordinates of the mobile device
AN5623 - Rev 1
[Show grid] Scalable grid
–
Figure 16. View coordinates
page 12/20
Figure 17. Show grid
AN5623
Start tracking
AN5623 - Rev 1
page 13/20
7 Record a tracking trace
BspLocClient provides the possibility to record the tracking data transmitted from the mobile device to the
computer via the USB connection (UART link) in a .csv file.
Step 1. Check tracking is running as described in Section 6 .
AN5623
Record a tracking trace
Figure 18. Tracking ready to be recorded
Step 2. In the [MEK Positioning] tab, click on [Browse] to select where the .csv file may be saved.
Step 3. Click on [Start Record].
Step 4. Click on [Stop Record] at the end of the sequence.
A .csv file is created in the directory specified at step 2. It contains timestamps in nanoseconds and x,
y, and z coordinates in meters. An example is given in Figure 19.
Figure 19. Tracking trace in tabular format
AN5623 - Rev 1
page 14/20
8 Ask for support
Additional information is available from the documents listed in References. All documents may be updated
without notice to individual users beforehand.
For up-to-date support or information about standardized as well as customized solutions, refer to the UWB and
product pages on www.st.com, or to the nearest STMicroelectronics office.
AN5623
Ask for support
AN5623 - Rev 1
page 15/20
Revision history
AN5623
Table 2. Document revision history
Date Revision Changes
20-Apr-2021 1 Initial release.
AN5623 - Rev 1
page 16/20
AN5623
Contents
Contents
1 General information ...............................................................2
2 Install BspLocClient ...............................................................3
3 Configure the topology (optional) ..................................................5
4 Set BspLocClient for MEK positioning .............................................6
5 Configuring the map ...............................................................8
6 Start tracking ......................................................................9
7 Record a tracking trace ...........................................................14
8 Ask for support...................................................................15
Revision history .......................................................................16
Contents ..............................................................................17
List of tables ..........................................................................18
List of figures..........................................................................19
AN5623 - Rev 1
page 17/20
AN5623
List of tables
List of tables
Table 1. List of acronyms ....................................................................2
Table 2. Document revision history ............................................................. 16
AN5623 - Rev 1
page 18/20
AN5623
List of figures
List of figures
Figure 1. Visualization of 3D modes in BspLocClient ................................................. 1
Figure 2. Dragged and dropped application icons to the left menu bar for quick access .........................3
Figure 3. BeSpoon Location Viewer icon .........................................................4
Figure 4. Application preferences adapted to MEK positioning ..........................................6
Figure 5. Use of BspLocClient without server connection .............................................. 6
Figure 6. MEK positioning choice in the Preferences menu ............................................7
Figure 7. Specify the offset and the scale on X and Y axes ............................................8
Figure 8. Request to continue without server connection ..............................................9
Figure 9. USB port selection and MEK positioning start ..............................................10
Figure 10. Devices info display ............................................................... 10
Figure 11. Viewer 2D vizualization ............................................................. 11
Figure 12. View Anchors .................................................................... 12
Figure 13. View Label...................................................................... 12
Figure 14. Trace.......................................................................... 12
Figure 15. View elevation ................................................................... 12
Figure 16. View coordinates .................................................................12
Figure 17. Show grid ......................................................................13
Figure 18. Tracking ready to be recorded ........................................................ 14
Figure 19. Tracking trace in tabular format........................................................ 14
AN5623 - Rev 1
page 19/20
AN5623
IMPORTANT NOTICE – PLEASE READ CAREFULLY
STMicroelectronics NV and its subsidiaries (“ST”) reserve the right to make changes, corrections, enhancements, modifications, and improvements to ST
products and/or to this document at any time without notice. Purchasers should obtain the latest relevant information on ST products before placing orders. ST
products are sold pursuant to ST’s terms and conditions of sale in place at the time of order acknowledgement.
Purchasers are solely responsible for the choice, selection, and use of ST products and ST assumes no liability for application assistance or the design of
Purchasers’ products.
No license, express or implied, to any intellectual property right is granted by ST herein.
Resale of ST products with provisions different from the information set forth herein shall void any warranty granted by ST for such product.
ST and the ST logo are trademarks of ST. For additional information about ST trademarks, please refer to www.st.com/trademarks. All other product or service
names are the property of their respective owners.
Information in this document supersedes and replaces information previously supplied in any prior versions of this document.
© 2021 STMicroelectronics – All rights reserved
AN5623 - Rev 1
page 20/20
Loading...