TeraBee TeraRanger Neo ES User manual

TeraRanger Neo ES
User manual
Version 1.0
Technical support: [email protected]
Sales and commercial support: [email protected]

Many thanks for buying our TeraRanger Neo ES sensor.
TeraRanger Neo ES is the next generation of TeraRanger range finders. By using indirect
ToF, TeraRanger Neo ES provides highly accurate distance measurements in a compact,
lightweight form, with exceptionally low power consumption. The front panel is
designed to enable integrations that can achieve IP65 protection.
This guide provides you with all the information needed to use and fully integrate our
sensor in your system.
If you have any questions or remarks regarding the product, please contact your
commercial representative or our technical support at [e-mail].
Copyright © Terabee 2022
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
2 / 17

Table of contents
1.About the TeraRanger Neo ES 4
1.1. Inside the package 4
1.2. Technical specifications 4
1.2. Symbols explanation 5
2.Sensor use 5
2.1. LED Indication 5
2.2. Connecting the TeraRanger Neo ES to a host computer 5
2.2.1. Windows OS 5
2.2.2. Example HTerm output 8
3.UART Communication 9
3.1. UART pinout 9
3.2. Electrical characteristics 10
3.3. Configuration commands 10
3.3.1. Command composition 10
3.3.2. List of commands 11
3.4. Sensor payload 12
3.5. Status codes 12
3.6. Distance error cases 14
3.7. Sample Python script to read data 14
3.8. In case of device failure 16
4. Sealed front panel and integration 17
Copyright © Terabee 2022
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
3 / 17

1.About the TeraRanger Neo ES
1.1. Inside the package
You will receive the following items when purchasing the TeraRanger Neo ES:
●TeraRanger Neo ES x1
●Molex cable Open-End x1
●Nylon screw (Flathead) M2 x 0.4 mm x 12 mm x2
●Nylon nut (Hex) M2 x 0.4 mm x2
●Rubber joint x 1 mm x1
●3M tape x 1 mm x1
1.2. Technical specifications
Product code
TR-NEO-ES
Performance
Detection principle
Infrared Indirect Time-of-Flight
Range*
0.2 - 30 m
Update rate
25 readings per second
Output resolution
1 mm
Accuracy
Approx. 1-2% of measured value
Field of View
Approx. 2.2°
Electronics
Supply voltage
5V DC +/-5%
Supply current (min-max)
250 mW on 5V rail (50 mA average)
Communication
Interface
LP UART, +3.3 V level (+/-5%), 9600,8,N,1
Connector
Molex - CONN HEADER SMD 4POS 1.25MM
Mechanical data
Dimensions
Height 30.5 mm; Width 15.5 mm; Depth 28.2 mm; Screw holes 2 mm
ø
Weight
Approx. 6 g
Operating conditions
0°C to 60°C (measured inside the sensor)
Ingress protection
Sealed front panel for potential IP65 integration
Eye safety
Yes
Conformity
Reference standard
CE, RoHS
Table 1 - Technical specifications
Copyright © Terabee 2022
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
4 / 17

* Specifications are derived from tests in controlled conditions. Bright sunlight, target surface
reflectivity and other variables will affect sensor performance. The combination of very bright
sunshine and low reflectivity targets (such as grass) can reduce maximum range. For additional
information, please find the following test results report.
1.2. Symbols explanation
The following symbols are used within the document:
This symbol indicates specific recommendations in order to run the sensor in the
intended way.
2.Sensor use
2.1. LED Indication
Two LED indicators are present on the PCB, and are visible through the back side.
The LED indicators can be used to troubleshoot the sensor.
LED designator
Description
Action
Green LED
flashes “8 times” on startup
then switches off
Normal startup behavior.
No action
Green LED
flashes at regular time
intervals of around 5
seconds
Green LED flashing indicates
normal sensor operation.
No action
Red LED
blinking rapidly at ~100ms
intervals.
Sensor has detected a fault in the
device and has stopped
functioning
Check the cable connector and
restart.
Table 2 - LED indicators
2.2. Connecting the TeraRanger Neo ES to a host
computer
2.2.1. Windows OS
Copyright © Terabee 2022
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
5 / 17

Hardware needed:
(1) TeraRanger Neo ES,
(2) Molex cable Open-End
(3) FTDI UART to USB
(not included)
(4) computer
(not included)
On Windows it is possible to use any terminal emulation software for data display.
Terabee often works with and suggests using HTerm software. Please follow the
provided link to download the software file (http://www.der-hammer.info/terminal/),
and select the version 0.8.5 of the software.
Next, extract the downloaded zip file to the selected folder, open it and double click on
the “HTerm.exe” document. Connect the TeraRanger Neo ES to a computer and select
the corresponding USB port (click “R” button to refresh the port list). Please configure
the software with the following parameters:
Baud rate : 9600 bit/s
Data bits : 8
Parity bit : None
Stop bit : 1
See Figure 1 below for visual instructions.
Figure 1 - HTerm parameters for TeraRanger Neo ES
Once the USB port is selected and the parameters correctly set, click on the “Connect”
button. The distance data will now appear in the “Received data” box (see Figure 2).
Copyright © Terabee 2022
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
6 / 17

Figure 2 - Data stream on HTerm software
To communicate with the terminal emulation software, a command in hexadecimal
needs to be sent using the “Type” field. Make sure the “Hex” checkbox is selected
(checked) and the “Type” field has “HEX” as an option selected. Figure 3 shows an
example of the command which enables low power mode.
Figure 3 - Example of command which enables low power mode
The data output format is in Hexadecimal. There is no other output format
available. See Figure 4 to easily understand how to read the distance values in
decimal format.
Copyright © Terabee 2022
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
7 / 17

2.2.2. Example HTerm output
Figure 4 - Example of HTerm output
If we look at the frame “T 06 41 C0 D9” as an example we have:
The real distance measured is: 1601 millimeters.
FRAME HEADER: T
MSB DISTANCE: 0x06
LSB DISTANCE: 0x41
STATUS CODE: 0xC0(16) = 1100 0000(2) => QF = 6(10)(value is between 90% & 100%)
CRC: 0xD9
Refer to the section Sensor payload which describes the payload in detail.
Copyright © Terabee 2022
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
8 / 17

3.UART Communication
The TeraRanger Neo ES is controlled through a UART interface.
3.1. UART pinout
The UART interface uses a single 4 pin Molex connector for interfacing to the host
system. The mating connector is a Molex - CONN HEADER SMD 4POS 1.25MM. Please
consider the mechanical stability of the mated connectors and avoid any kind of excess
force on the connector (during installation and once integrated).
Pin
Designator
Description
1
5 V
+5 V supply input
2
Tx
UART transmits output. 3.3 V logic
3
Rx
UART receives input. 3.3 V logic
4
GND
Power supply and interface ground
Table 3 - Pinout and description
Figure 5 - Wiring connection Neo ES sensor to a computer
Copyright © Terabee 2022
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
9 / 17

3.2. Electrical characteristics
Parameter
Minimum
Maximum
Average
Power supply
Voltage input (V)
Current consumption (mA)
4.5 V
45 mA
5.5 V
55 mA
5 V
50 mA
Interface logic levels
(referenced to +3V3)
LOW
HIGH
-
2.3
1
-
-
-
Table 4 - TeraRanger Neo ES power consumption
3.3. Configuration commands
3.3.1. Command composition
The Query (Q):
The query frame contains length (in bytes is the sum of the length, command and data),
command code, N bytes of the data and a CRC-8 checksum of the entire frame in the
last byte, for the commands that only read data, the query will not include any data
bytes, but the response will.
The Response (R):
The response contains :
●The length of the reply message without the CRC-8 byte
●The command code (same code that was received)
●Data (only if the query was to read data from the device) otherwise ACK or NACK
●CRC-8 calculated for the entire message without the actual CRC byte (i.e. from
length byte to the last data byte, both included)
Length
Represents the sum of the length, command and the data transmitted.
Contents of the Data Field
Copyright © Terabee 2022
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
10 / 17

The Data Field contains the data corresponding to the Command to be executed. The
data field cannot be empty.”
1. An ACKnowledged message contains length, current command, Data and CRC.
2. Non-ACKnowledged message contains length, current command, ”command
NACK/CRC mismatch /unknown command” and CRC.
Contents of the CRC-8 Field
The error checking field contains an 8 bit value which is the result of a Cyclic
Redundancy Check (CRC) calculation performed on the message contents.
The CRC field is appended to the message as the last field in the message.
Error handling case:
The failure case : a mismatch is detected between the length byte and the actual
data sent or an unknown command or command not executed.
The reply will be a 4 bytes frame:
Length
Command
Command Error
0x00- No Error/No data
0xFF- NACK
0xCC - Crc mismatch
0xEE - Unknown command
CRC-8
Each command message frame must be transmitted in a continuous stream, i.e.
not byte by byte
It is advised to maintain a time interval of a few microseconds between two
messages for proper command registration
3.3.2. List of commands
Description
Query in HEX
Response in HEX
ENABLE LOW POWER
Sensor goes into low
power mode
0x03 0x07 0xA2 0xB1
0x03 0x07 0xXX CRC
Where XX can be an ACK or NACK
LOW POWER WAKEUP
Sensor wakes up from
0x03 0x08 0xA3 0x75
0x03 0x08 0xXX CRC
Where XX can be an ACK or NACK
Copyright © Terabee 2022
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
11 / 17

low power mode
DEVICE RESET
Performs a soft reset
0x02 0x05 0x31
The device performs a software reset.
Normal startup logic follows (200ms
delay until data starts streaming).
Table 5 - Valid sensor commands
Please refer to Connecting the TeraRanger Neo ES to a Host Computer for instructions
on how to send commands to the sensor using a host computer and the HTerm
emulation software
3.4. Sensor payload
This mode provides users with measured distances displayed in the form of binary
messages using 5 bytes: TXXSCRC8.
The Payload will contain 3 bytes of data (2 for distance in mm, 1 status byte), and 2
metadata bytes (header and checksum).
Status byte: Two bits to indicate overtemperature (>50°C) and critical temperature
(>60°C) , three bits to indicate the status of distance measurement and three bits to
indicate the quality factor of the distance measurement.
The checksum byte is calculated out of the first 4 bytes of the message (header byte,
distance reading bytes, and status code byte)
Header (1 byte) : T (84 decimal / 0x54 hex)
Distance reading in mm (2 bytes) : XX (MSB, LSB)
Status Code Byte (1 Byte) : S (One byte to indicate code status of distance
measurement. See the Status Codes section below).
Checksum (1 byte) : CRC8
Byte 1
“T”
FRAME HEADER
Byte 2
MSB
DISTANCE
Byte 3
LSB
DISTANCE
Byte 4
STATUS CODE
Byte 5
CRC-8
3.5. Status codes
Certain status codes will be detected and reported by the firmware using the 4th byte of
the payload. Each bit in the byte represents a status flag as described below.
High nibble Low nibble
Copyright © Terabee 2022
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
12 / 17

BIT 0
QUALITY_FACT
OR
BIT 1
QUALITY_FACT
OR
BIT 2
QUALITY_FACT
OR
BIT 3
DISTANCE_STA
TUS
BIT 4
DISTANCE_STA
TUS
BIT 5
DISTANCE_STA
TUS
BIT 6
CRITICAL_TEMP
Critical
temperature
(>60°C)
BIT 7
OVER_TEMP
Overtemperate
(>50°C)
Quality factor bits - (Signal quality level):
The sensor gives out a quality factor for every distance measurement with a value from
0 - 100 and this is converted to 3 bits from value to 0 to 6 where 0 is very poor and 6 is
best quality.
Quality Factor
Value
0 - 25
0
25 - 50
1
50 - 60
2
60 - 70
3
70 - 80
4
80 - 90
5
90 - 100
6
DISTANCE_STATUS:
Gives the status of the distance measurement using values between 0 and 4, where:
●0 => no error
●1 => min range
●2 => out of range
●3 => ambient light too high
●4 => invalid reading
OVER_TEMP: If this bit is set (1), the device is above 50°C
CRITICAL_TEMP: If this bit is set (1), the device is above 60°C
The sensor will output T01CRC (first distance byte set to zero and the second to
one) as an error message if the sensor is unable to measure a distance. Please
refer to Distance error cases for more details about error cases.
Copyright © Terabee 2022
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
13 / 17

3.6. Distance error cases
Error cases output
BINARY
Detection below sensors minimum range
0X0000
Detection beyond sensors maximum range
0XFFFF
Invalid reading:
- out of range
- ambient light too high
- invalid reading
0x0001
Note that in some cases, the sensor might not distinguish properly between errors
i.e. if below minimum range but then a reading comes with very poor quality, the
error will change to “Invalid reading”
3.7. Sample Python script to read data
This sample code is a goodwill gesture to our customers. It is made to help our
customers speed up their applications. This sample code is not made to be copy
and paste as each customer has a different setup.
#!/usr/bin/env python3
#---------------------------------------------------------------------------
-
# Created By : TERABEE
# Created Date: 01-03-2022
# version ='1.0'
#
---------------------------------------------------------------------------
import serial, time
import serial.tools.list_ports
quality_factor_mask = 224
status_mask = 28
print('Searching Ports...')
Copyright © Terabee 2022
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
14 / 17

ports = serial.tools.list_ports.comports(include_links =False)
for port in ports :
print('Find port '+ port.device)
ser = serial.Serial(port.device)
if ser.isOpen():
ser.close()
ser = serial.Serial(port.device,9600,timeout=1)
ser.flushInput()
ser.flushOutput()
print('Successfully Connected to ' + ser.name)
while True:
try:
data = ser.read()
if data == b'\x54':
raw = ser.read(3)
dist = int((list(raw)[0] << 8) | list(raw)[1])
full_status = list(raw)[2]
status = full_status & status_mask
qf = full_status & quality_factor_mask
if(status == 0x00):
status_response = "Reading status: No error"
elif(status == 0x04):
status_response = "Reading status: Minimum Range"
elif(status == 0x08):
status_response = "Reading status: Out of Range"
elif(status == 0x0C):
status_response = "Reading status: ambient lightning high"
elif(status == 0x10):
status_response = "Reading status: invalid reading"
if(qf == 0xC0):
qf_response = "QF is 90-100%"
elif(qf == 0xA0):
qf_response = "QF is 80-90%"
Copyright © Terabee 2022
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
15 / 17

elif(qf == 0x80):
qf_response = "QF is 70-80%"
elif(qf == 0x60):
qf_response = "QF is 60-70%"
elif(qf == 0x40):
qf_response = "QF is 50-60%"
elif(qf == 0x20):
qf_response = "QF is 25-50%"
elif(qf == 0x00):
qf_response = "QF is 0-25%"
print('ToF Distance in [mm]:',dist,qf_response,status_response)
ser.flushInput()
except:
print("Keyboard Interrupt")
break
3.8. In case of device failure
In case of device failure, perform the following troubleshooting list:
If RED LED is blinking:
●Check the wiring in your setup
○Ensure correct PIN 1 position
○RX from the TeraRanger Neo ES goes to TX of FTDI
○TX from the TeraRanger Neo ES goes to RX of FTDI
●Sensor needs to be powered with 5V and not with 3.3 V
●Ensure that your power supply can provide at least 250mW at 5V
If this sequence does not work, contact your commercial representative or our technical
support team at [email protected] and indicate the following information:
●Describe in details your setup
●Pictures of your wiring in details
●Video of the LED sequence
●Detailed description of your FTDI
Copyright © Terabee 2022
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
16 / 17

4. Sealed front panel and integration
The front panel of the TeraRanger Neo (the black screen of the sensor) is sealed for a
high degree of ingress protection. It may be possible to achieve IP65 protection with the
proper integration. The rubber gasket or 3M tape, both included, can help achieve a
secure integration.
Front panel in detail
Rubber gasket
3M double-sided tape
It is the customer's responsibility to test and validate the final IP rating of the sensor
integration.
We suggest tightening the screws (included) gently with a maximum torque of
0.1Nm . The use of a washer is recommended (not included).
The name TERABEE® and the ® are registered trademarks in the following countries: China, European Union, France, South Korea,
Switzerland,Taiwan, United Kingdom and United States.
Terabee reserves the right to make changes, corrections, modifications or improvements to this document, and the products and services
described herein at any time, without notice.
Copyright © Terabee 2022
Terabee, 90 rue Henri Fabre
01630 Saint-Genis-Pouilly, France (next to CERN)
17 / 17