TeraBee TeraRanger Multiflex User manual

TeraRanger Multiflex
Installation and operation
manual
Version 1.1
Technical support: terabee.com/support
Sales and commercial support: [email protected]

Table of contents
1. About the TeraRanger Multiflex 2
1.1. Inside the package 2
1.2. Safety note 2
1.3. Dimensions and mounting 2
1.4. Details on supply voltage 4
1.5. About the connector 5
1.6. UART data interface (default) 6
1.7. I2C data interface 6
1.8. USB interface 7
1.9. Normal operation 7
2. Assembly 7
Step 1. Sensor positioning 7
Step 2. Connecting the Flex Cable to the sensor 9
Step 3. Connecting sensors to each other 10
Step 4. Joining the strip of sensors to TeraRanger Multiflex Hub 10
Step 5. Ready to test 10
3. Connecting the TeraRanger Multiflex using a computer with a serial console 11
3.1. Windows 11
3.2. MacOS 13
3.3. Linux 14
4. UART & USB protocol description 16
4.1. Basic commands (UART & USB) 16
4.2. Printout modes 17
4.3. Configuring TeraRanger Multiflex sensors 19
4.4. Instructions on sensor configuration 19
5. I2C protocol description 21
6. Running the TeraRanger Multiflex in ROS 23
7. Laser safety considerations 24
Copyright © Terabee 2023
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
TeraRanger Multiflex
Installation and operation manual
Version 1.1
2 / 26

1.About the TeraRanger Multiflex
1.1. Inside the package
You will receive the following items when purchasing the TeraRanger Multiflex:
●8 assembled sensors with covers
●Multiflex Hub with case
●8 flat flex cables (10 cm)
●Micro USB cable (50 cm)
●DF13 7 pin cable, Open-End (22 cm)
Up to 4 additional covers are included in the package. If a sensor is not performing as
expected, try using one of the spare covers as dirty, dusty or scratched covers can
impede sensor performance.
1.2. Safety note
Each TeraRanger Multiflex sensor contains a laser emitter and corresponding drive
circuitry. The laser output power must not be increased by any means and no optics
should be used with the intention of focusing the laser beam.
Copyright © Terabee 2023
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
TeraRanger Multiflex
Installation and operation manual
Version 1.1
3 / 26

1.3. Dimensions and mounting
TeraRanger Multiflex sensors are enclosed with polycarbonate covers. For optimal
performance please make sure that the covers are touching the sensor’s PCB by
screwing the sensor units to a flat surface using M3 screws.
The TeraRanger Multiflex provides two mounting holes on both: (a) the TeraRanger
Multiflex Hub (Figure 1), and (b) the sensor units (Figure 2). Both pairs of mounting holes
are designed for M3 screws. The individual distances between the holes, and the sensor
external dimensions are illustrated in the two figures below.
Figure 1. TeraRanger Multiflex Hub dimensions in millimeters
Copyright © Terabee 2023
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
TeraRanger Multiflex
Installation and operation manual
Version 1.1
4 / 26

Figure 2: TeraRanger Multiflex sensor dimensions in millimeters
The following aspects should be taken into consideration when mounting the
TeraRanger Multiflex:
●Do not remove the plastic covers as this will misalign the optics and degrade the
sensor’s performance.
●Sensors should not be connected or disconnected from the strip while the Multiflex
is powered.
●Do not mount the TeraRanger Multiflex Hub onto hot surfaces or near other
sources of heat. If possible, allow the board to properly radiate its heat or mount it
in a ventilated place.
●Take all usual precautions for sensitive electronics such as maintaining a suitable
distance from strong electric and magnetic fields, strong radio emitters, etc.
●Maintain a clean mounting environment (dust entering behind the lens can severely
affect performance).
1.4. Details on supply voltage
TeraRanger Multiflex Hub works with a supply voltage of 5 V +-0.25 V. Please make sure
that the supply voltage has low ripple and avoid strong inductive loads on the same
supply to keep it free of voltage spikes and drops.
1.5. About the connector
The TeraRanger Multiflex Hub connects to your equipment using the 7-pin connector
from the Hirose DF13 series, included. (The part number of the corresponding female
connector is DF13-7S-1.25C.) The TeraRanger Multiflex includes a connector cable.
Please use Figure 3 and following table to identify the pins:
Copyright © Terabee 2023
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
TeraRanger Multiflex
Installation and operation manual
Version 1.1
5 / 26

Figure 3. TeraRanger Multiflex Hub
Pin Function
7 GND
6 RX Serial In (UART)
5 TX Serial out (UART)
4 Interrupt pin
3 SDA with pull up resistor (I2C)
2 SCL with pull up resistor (I2C)
1 5 V
Important:
●Once connected, DF13 connectors are very reliable and are perfect for robotics
and drone environments where vibrations are common. These connectors are
not designed for continuous plugging and unplugging. If you need to plug and
unplug the sensors frequently, consider adding a more suitable connector
in-line.
●Please do not apply force to the connector when pushing it in the socket. Ideally,
press the socket down to the PCB with your thumb and push the connector in
with your other hand. Do not use tools like pliers etc.
●Please follow basic rules on ESD safety when connecting and touching the
TeraRanger Multiflex or TeraRanger Multiflex Hub.
Do not plug/unplug sensors from the TeraRanger Multiflex Hub while the device is
powered. Always disconnect the power supply first.
1.6. UART data interface (default)
UART is available on pins 5 and 6. It accepts input voltage levels from 3.3 V up to 5 V.
The output voltage level is 3.3 V. Please use a serial to USB interface (e.g. FTDI breakout
boards) to connect the TeraRanger Multiflex Hub to a computer via the UART interface.
Copyright © Terabee 2023
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
TeraRanger Multiflex
Installation and operation manual
Version 1.1
6 / 26

Do not connect the TeraRanger Multiflex Hub to a real RS232 PC port, the voltage
levels are different and this might destroy the board's electronics.
The UART interface is configured to send and receive data at a transfer speed of 115200
bit/s with 8 data bits, no parity bit and one stop bit (115200-8N1). More information on
the different operation modes can be found in Section 5. Protocol description of this
manual.
1.7. I2C data interface
Another way to connect to the TeraRanger Multiflex Hub is via I2C interface. Using this
interface, you can connect a TeraRanger Multiflex sensor strip to an I2C master. In the
current firmware version, the I2C base address is fixed to 0x55.
Please consider that, due to the fixed I2C base address, you can only run one
TeraRanger Multiflex per I2C bus. Nevertheless, you can connect other devices with
different base addresses to the same bus, but please make sure that the I2C master of
the bus can still drive the sum of all pull-up resistors on the bus.
Please refer to Section 1.5 (About the Connector) for the electrical connections to be
made for using I2C. The signal levels are 3.3 V, the maximum bus speed is 400 kHz and
the pull-up resistors (1.5 kOhms) are already integrated in the TeraRanger Multiflex
Hub.
1.8. USB interface
You can directly connect the TeraRanger Multiflex Hub to your computer using a micro
USB cable. This cable will provide power and data communication.
For both Linux and Mac operating systems, a driver for this interface is already installed
and the interface will appear as a virtual COM port. It is configured to send and receive
at 115200 bit/s with 8 data bits, no parity bit and one stop bit (115200- 8N1).
If you are using Windows, please download the driver from
http://www.st.com/en/development-tools/stsw-stm32102.html
and carefully follow the ”ReadMe file” instructions given by the installer . After successful
installation, unplug the interface for a moment and plug it back in. The virtual COM port
should now be available on your PC.
Do not plug and/or unplug the sensor units while the TeraRanger Multiflex is powered
by a computer. Disconnect the USB cable first.
Copyright © Terabee 2023
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
TeraRanger Multiflex
Installation and operation manual
Version 1.1
7 / 26

1.9. Normal operation
Each time the TeraRanger Multiflex Hub is powered, the GREEN LED will turn on. At the
same time, the Hub will detect how many sensors are connected. The ORANGE LED will
blink once for each sensor detected. It can take a few seconds before the distance
values become available on the UART, USB and/or I2C interfaces. Once available, a BLUE
LED will start blinking, indicating that the distances are being sent continuously to UART,
USB or I2C interfaces (See Figure 4).
Figure 4. LED orientation on the TeraRanger Multiflex Hub
Copyright © Terabee 2023
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
TeraRanger Multiflex
Installation and operation manual
Version 1.1
8 / 26

2. Assembly
Please follow these five simple steps illustrating a tutorial on how to connect 8 sensors
to the TeraRanger Multiflex Hub.
Step 1. Sensor positioning
Before connecting, make sure that the sensors are (1) positioned in the correct numeric
order and (2) facing the same direction (See Figure 5).
Figure 5. Sensor ascending numeric order
Each sensor is marked with a number (1 to 8), and a direction arrow for connection
(Figure 5). Please double-check that the sensor units are placed in ascending order (1, 2,
3, 4, etc.) and that they all face the same direction. In cases when less than 8 sensors are
used, always start with the sensor containing the lowest number and then connect
subsequent sensors in ascending numeric order.
TeraRanger Multiflex will not stream distance data if any of the sensor units are
connected in the wrong order or direction. See example in Figure 6.
Figure 6. Incorrect sensor order and direction
Copyright © Terabee 2023
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
TeraRanger Multiflex
Installation and operation manual
Version 1.1
9 / 26

Step 2. Connecting the Flex Cable to the sensor
Start by plugging the Flex Cable to the sensor’s Flexible Flat Cable (FFC) connector.
Figure 7. Open, Insert, Close
Note that each of the FFC connectors needs to be manually opened and then closed
when connecting the Flex Cables as shown in Figure 7.
For easier opening you can gently pull the small locking ‘tabs’ on the sides of the
connector before pulling the connector down. You may find this easier with tweezers.
The locking mechanism has to be pulled out only a millimeter or less, not entirely.
Note that too much force can damage the sensor’s connector. Also, double check that
the Flex Cable is plugged in a straight manner to avoid a short-circuit.
When connecting the Flex Cable, make sure that the side with conductive tracks is facing
the sensor’s Printed Circuit Board as shown in Figure 7. Connecting the wrong side of
the cable can damage both the sensor and/or the cable (Figure 8). Once the cable is
positioned inside the connector, close the connector by smoothly pushing in the locking
mechanism.
Figure 8. Left image - correct Right image - incorrect
Copyright © Terabee 2023
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
TeraRanger Multiflex
Installation and operation manual
Version 1.1
10 / 26

Step 3. Connecting sensors to each other
Continue to connect all 8 sensor units together respecting their assigned numerical
order (Figure 9).
Figure 9. Correct connection of 8 sensor units
Step 4. Joining the strip of sensors to TeraRanger
Multiflex Hub
Connect the strip of 8 sensors to the TeraRanger Multiflex Hub (Figure 10). The Hub also
contains an FFC connector, so you need to respect the connecting guidelines as
described in Step 2.
Figure 10. Connecting sensor units to TeraRanger Multiflex Hub
Important: Sensor 1 always needs to be directly connected to the TeraRanger
Multiflex Hub. The direction arrow must always point away from the TeraRanger
Multiflex Hub. In cases when sensor number 1 is not used, please connect the sensor
with the lowest numeric value.
Step 5. Ready to test
Once fully assembled, the TeraRanger Multiflex is ready for testing on your computer
(Figure 11). Use the micro USB cable, provided in the package, to connect the
TeraRanger Multiflex Hub with a computer.
Copyright © Terabee 2023
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
TeraRanger Multiflex
Installation and operation manual
Version 1.1
11 / 26

Figure 11. TeraRanger Multifex assembled
Copyright © Terabee 2023
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
TeraRanger Multiflex
Installation and operation manual
Version 1.1
12 / 26

3. Connecting the TeraRanger Multiflex
using a computer with a serial console
TeraRanger Multiflex can interact with any serial console using the following
configuration, both for USB, UART and I2C interfaces: 115200 bit/s, 8 data bits, no parity
bit and one stop bit.
3.1. Windows
In Windows, you can use terminal emulation software of your choosing, however we
suggest you use HTerm (http://www.der-hammer.info/terminal/). Extract the
downloaded zip file to the folder of your choice, open it and double click on the
“HTerm.exe” document.
Connect the TeraRanger Multiflex to your computer and select the corresponding USB
port (click “R” button to refresh the port list). Select values for the following fields: (1)
Baudrate, (2) Data Bits, (3) Parity, (4) Stop Bits. For easier readings, select the “CR+LF”
option for “Newline at” tab. See Figure 12 for visual instructions.
Figure 12. Connecting the USB Port
Once you have selected the USB port and required values, click on the “Connect” button.
The data will now appear in the “Received data” box (See Figure 13).
Figure 13. H-Term Main Interface
Copyright © Terabee 2023
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
TeraRanger Multiflex
Installation and operation manual
Version 1.1
13 / 26

To communicate with the terminal emulation software, you need to send a command in
hexadecimal via the “Type” box. First check the “Hex” checkbox and choose the “HEX”
Type. Figure X gives the example of the command which allows data to be shown in
TEXT mode when 8 sensor units are used. Please see Section 4.1 for basic commands.
3.2. MacOS
In MacOS we recommend using a serial port terminal application such as CoolTerm
(http://freeware.the-meiers.org/). In the link, please scroll down to find the download
file.
Extract the downloaded zip file to the folder of your choice, open it and double click on
the “CoolTerm.exe” document. The emulation software window should open. Now
connect the TeraRanger Multiflex Hub to your computer, and click the “Options” button
in the toolbar (See Figure 14).
Figure 14. CoolTerm Toolbar
In the “Serial Port” tab please select the corresponding USB port (Click “Re-scan” if the
USB is not detected). Select values for following fields (Baudrate, Data Bits, Parity, Stop
Bits) as shown in Figure 15.
Figure 15. Serial Port Setup
After, in the “Terminal Tab” (Figure 16) make sure the following fields are selected:
1. Terminal Mode: Raw Mode
2. Enter Key Emulation: CR+LF
Once done, click “OK” to apply changes.
Copyright © Terabee 2023
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
TeraRanger Multiflex
Installation and operation manual
Version 1.1
14 / 26

Figure 16. Terminal Setup
In the toolbar, click the “Connect” button to start the data stream.
Figure 17. Sending commands
To send commands, in the Menu bar click “Connection” and after “Send string” (shortcut:
cmd+T) as shown in Figure 17. Select the “Hex” option as the commands are given in
hexadecimal values (Figure 18). See Section 4.1 for basic commands.
Figure 18. Sending hexadecimal values.
You can find more information about using CoolTerm at the following address:
https://learn.sparkfun.com/tutorials/terminal-basics/coolterm-windows-mac-linux
Copyright © Terabee 2023
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
TeraRanger Multiflex
Installation and operation manual
Version 1.1
15 / 26

3.3. Linux
Using Linux Ubuntu, please use the Cutecom application for data stream via computer.
To do so, first download and then update the application via the terminal software. Use
following commands in your Linux shell window:
1. sudo apt-get update
2. sudo apt-get install cutecom
3. cutecom
The application automatically runs after launching the command “cutecom”. Next, enter
the corresponding Device name by sending the following command in your Linux shell
window:
ls /dev/tty*
The device name is usually /dev/tty/ACM0 or /dev/tty/ACM1 (Figure 19).
Figure 19. Recognizing Device Name
In the main interface, make sure to fill the following fields (Baud rate, Data bits, Parity,
Stop bits) as shown in Figure 20.
Figure 20. Baud rate, Data bits, Parity, Stop bits
Click the “Open Device” button to start the data stream in millimeters. Note that
distance values are separated from each other via the character “\0x09”.
Copyright © Terabee 2023
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
TeraRanger Multiflex
Installation and operation manual
Version 1.1
16 / 26

Should you see an error stating that the opening has failed then try sending the
following command directly from the Linux shell window to grant access to the serial
port.
sudo chmod a+rw /dev/ttyACM0
To send commands, the TeraRanger Multiflex uses a Python script. Please follow the
ReadMe file (available also on the download section teraranger-multiflex) from the
Python script to send the commands.
Copyright © Terabee 2023
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
TeraRanger Multiflex
Installation and operation manual
Version 1.1
17 / 26

4. UART & USB protocol description
4.1. Basic commands (UART & USB)
Action type
Mode name / Action
Hex command
Modify PRINTOUT
MODE
TEXT
00 11 01 45
BINARY
00 11 02 4C
Configure the
number of sensors
to be used
To use all sensors (8 units)
00 52 FF 3E
To use only the first 4 sensors
00 52 03 0F E0
To use other amount of sensors
See Section 4.4 for
configuration
Answer to the basic commands
Each time a command is sent, the user will receive an answer that will inform whether it
is an affirmative (acknowledge) or a negative (non-acknowledge) answer.
Action type
Type of answer
Hex command
Modify PRINTOUT
MODE
acknowledge
52 45 11 00 D4
non-acknowledge
52 45 11 FF 27
Configure the
number of sensors
to be used
acknowledge
52 45 52 00 B0
non-acknowledge
52 45 52 FF 43
4.2. Printout modes
TeraRanger Multiflex firmware supports two printout modes which can be selected by
sending the corresponding hexadecimal command to the Multiflex using the serial
terminal application (See Section 3 for detailed instructions). Please note that the
default mode is binary.
Copyright © Terabee 2023
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
TeraRanger Multiflex
Installation and operation manual
Version 1.1
18 / 26

Mode
Description
Command
Binary
mode
Data output (20 bytes message):
MFXXXXXXXXXXXXXXXXYCRC8
●Header (two characters): M (77 decimal / 0x4D hex)
and F (70 decimal / 0x46 hex)
●Distance reading in millimeters** (2 bytes per
sensor): XX
●8-bit-mask indicating if sensor is connected (1) or
not (0):Y
●Checksum (1 byte) of previous 19 bytes: CRC8
** if a sensor is not connected, or the interface board is
unable to obtain a distance measurement from the
sensor, the associated distance value is replaced by the
hexadecimal value 0xFFFF. You can figure out if a sensor
is connected or not reading by evaluating the 8-bit-mask
Y.
00 11 02 4C
Text
Mode
Data output (28 - 52 bytes message):
In HTerm:
MF\txxxx\txxxx\txxxx\txxxx\txxxx\txxxx\txxxx\txxxx\r\n
●Header (two characters): M (77 decimal / 0x4D hex)
and F (70 decimal / 0x46 hex)
●Tabulation between each measurements: \t (9
decimal / 0x09 hex)
●Distance reading in millimeters* (maximum 5
bytes per sensor): xxxx
●Carriage return character: \r (13 decimal / 0x0D
hex)
●New line character: \n (10 decimal / 0x0A hex)
* if a sensor is not connected or the interface board is
unable to obtain a distance measurement from the
sensor, the associated distance value is replaced by -1
00 11 01 45
Copyright © Terabee 2023
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
TeraRanger Multiflex
Installation and operation manual
Version 1.1
19 / 26

4.3. Configuring TeraRanger Multiflex sensors
All commands are a series of bytes. They respect the following format:
Byte n°
0
1
2
3
Element
Header
Command
Mask
CRC - 8
The header is one byte: (0 decimal / 0x00 hex)
The command field is a byte that indicates which action you want to perform (example
modify the running mode)
The mask field depends on the command. The Data Field contains the data
corresponding to the Command to be executed. The Data Field cannot be empty.
The error checking field contains an 8 bit value which is the result of a Cyclical
Redundancy Check (CRC) calculation performed on the message contents
4.4. Instructions on sensor configuration
The TeraRanger Multiflex can be used with less than 8 sensors. This allows the sensors
to work at higher update frequencies. To enable this, the user needs to inform the
terminal emulation software about the sensor units to be used by inputting the correct
command line. This section shows an example of how to configure 5 sensors (Figure 21).
Header
Command name /
byte
Sensor Mask /
byte
CRC - 8
Full Command
Example
0x00
Configure the number
of sensors to be used
/ 0x52 0x03
This byte depends
on how many
sensors you are
using
Depends
on the
sensors
mask byte
00 52 03 xx xx
The “Header” and the “Command name” byte values remain always the same: 00 52 03,
despite the amount of sensors used in an application.
The following 3 steps provide guidelines on how to calculate the remaining “Sensor
Mask” and “CRC” byte values:
Copyright © Terabee 2023
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
TeraRanger Multiflex
Installation and operation manual
Version 1.1
20 / 26