Commit 2eebb987 authored by Conor Smyth's avatar Conor Smyth

repaired broken image links

parent 34dd36bc
![Toposens](https://gitlab.com/toposens/public/resources/-/raw/master/ToposensPNG.png)
![Toposens](/Images/ToposensPNG.png)
In this repository you will find all resources for Toposens 3D ultrasonic sensors.
## Documents in this repository
* [TS3 Spec sheet](https://gitlab.com/toposens/public/resources/blob/master/TS3/ts3-specs.md)
* [TS3 Spec sheet](https://gitlab.com/toposens/public/resources/blob/master/TS3/ts3-specs.md)
* [TS3 Setup guide - Ubuntu](https://gitlab.com/toposens/public/resources/blob/master/TS3/ts3-setup-guide-ubuntu.md)
* [TS3 Setup guide - Windows 10](https://gitlab.com/toposens/public/resources/blob/master/TS3/ts3-setup-guide-windows10.md)
* [TS3 Communication protocol guide](https://gitlab.com/toposens/public/resources/blob/master/TS3/ts3-communication-protocol.md)
......@@ -11,7 +11,7 @@ In this repository you will find all resources for Toposens 3D ultrasonic sensor
* [TS3 Descriptions of known issues of TS3 and their mitigations](https://gitlab.com/toposens/public/resources/blob/master/TS3/ts3-known-issues.md)
## Further resources
* Find instructions on using **ROS packages** for Toposens sensors on the [ROS Wiki](http://wiki.ros.org/toposens).
* Find instructions on using **ROS packages** for Toposens sensors on the [ROS Wiki](http://wiki.ros.org/toposens).
* Find **sample scripts in Python** for Toposens sensors on [GitLab](https://gitlab.com/toposens/public/python-examples).
## Requirements to follow guides and tutorials
......
![Toposens](https://toposens.com/wp-content/themes/toposens/assets/img/logo2.png)
![Logo](/TS3/Images/logo2.png)
# TS3 - Communication Protocol
This guide explains the communication with TS3, both for the serial protocol and the physical interface. Find all resources for TS3 on [GitLab](https://gitlab.com/toposens/public/resources/).
......@@ -8,7 +8,7 @@ TS3 uses asynchronous serial input/output communication in ASCII format to send
Messages begin with the character `S` and end with the character `E`. Two types of messages are sent by TS3: **scan messages** and **acknowledgment messages**.
* Scan messages contain the information about objects that have been detected by TS3. This is the default message type.
* Acknowledgment messages acknowledge commands issued to TS3. This type of message occurs once directly after succesful booting of the device and once after every command that has been issued to TS3.
* Acknowledgment messages acknowledge commands issued to TS3. This type of message occurs once directly after successful booting of the device and once after every command that has been issued to TS3.
Commands sent to TS3 allow to set the sensor's parameters or to get information stored on the sensor. TS3 can handle only **one command at a time**. Another command can be triggered once processing of the previous command has been acknowledged by an acknowledgment message.
......@@ -24,24 +24,24 @@ Length of string: `S******` = **7 characters**
The characters after `S` store additional information about the scan, with the default content of the start marker being `S000000`. A scan that has been flagged as **noisy** has the start marker `S100000`.
### Points
### Points
Structure for each point: `P0000` `X` `<x-coordinate>` `Y` `<y-coordinate>` `Z` `<z-coordinate>` `V` `<v-value>`
Length of string: `P0000X*****Y*****Z*****V*****` = **29 characters**
Data contained in each point: coordinates x, y & z in millimeters; relative signal strength v in range 0 to 255.
Axis orientation (spatial measurements in x, y, & z) conform to the ROS coordinate frame convention defined in [REP 103](https://www.ros.org/reps/rep-0103.html#coordinate-frame-conventions):
Axis orientation (spatial measurements in x, y, & z) conform to the ROS coordinate frame convention defined in [REP 103](https://www.ros.org/reps/rep-0103.html#coordinate-frame-conventions):
![axis orientation](http://toposens.com/wp-content/uploads/2019/07/ts3-axis-illustration.png)
![axis orientation](/TS3/Images/ts3-axis-illustration.png)
### End Marker
The end of a scan message is indicated by the single character `E`.
The end of a scan message is indicated by the single character `E`.
### Example for a Scan Message
Example for a scan message containing only a single point:
S000000P0000X00285Y-0184Z-0374V00050E
S000000P0000X00285Y-0184Z-0374V00050E
For the scan message in the example above, the output is:
......@@ -55,16 +55,16 @@ For the scan message in the example above, the output is:
|`Z-0374`| z-coordinate = -374 mm |
|`V00050`| v-value = 50 |
|`E`| End of scan |
## Commands and Acknowledgment Messages
There are two types of commands, that can be sent to TS3: "set"- and "get"-commands.
While the first allows to adapt the sensor's settings and trigger an acknowledgement message, which is returned by the sensor,
the second issues a request, which returns information from the sensor's firmware.
While the first allows to adapt the sensor's settings and trigger an acknowledgment message, which is returned by the sensor,
the second issues a request, which returns information from the sensor's firmware.
> **Please note:**
> * TS3 only receives a single command at a time.
> **Please note:**
> * TS3 only receives a single command at a time.
> * Default values for parameters are applied at start up.
In case multiple commands are to be sent to TS3 at once, it is necessary to wait for the acknowledgment message for each respective command before issuing the next command.
......@@ -87,17 +87,17 @@ Length of string: `C**********\r` = **13 characters**
### Acknowledgement Messages
Structure for each acknowledgement message: `S` `<command number>` `C` `<repetition of command value>` `E`
Structure for each acknowledgment message: `S` `<command number>` `C` `<repetition of command value>` `E`
Length of string: `S00000*C*****E` = **14 characters**
Acknowledgment messages are sent once the associated command has been processed.
Acknowledgment messages are sent once the associated command has been processed.
| **Message** | **Associated Command** | **Example** |
|:-----------:|:-----------------------:|-------------|
|`S000001C*****E`|`sReje`| Message `S000001C00001E` acknowledges that echo rejection threshold parameter has been set to `1` by command `CsReje00001\r`. |
|`S000002C*****E`|`sNois`| Message `S000002C05000E` acknowledges that noise indicator threshold parameter has been set to `0.5`by command `CsNois05000\r`. |
|`S000003C*****E`|`sPuls`| Message `S000003C00010E` acknowledges that number of pulses parameter has been set to `10` by command `CsPuls00010\r`. |
|`S000003C*****E`|`sPuls`| Message `S000003C00010E` acknowledges that number of pulses parameter has been set to `10` by command `CsPuls00010\r`. |
|`S000004C*****E`|`sPeak`| Message `S000004C00003E` acknowledges that peak detection window parameter has been set to `3` by command `CsPeak00003\r`. |
|`S000005C*****E`|`sTemp`| Message `S000005C00220E` acknowledges that temperature parameter has been set to `22.0° C` by command`CsTemp00220\r`. |
......@@ -105,11 +105,11 @@ Acknowledgment messages are sent once the associated command has been processed.
### Special Case: Mode Command
This "set"-command allows to put the sensor into a specific scan mode. There are two currently available:
* Mode 0: **continuous scanning**, the sensor scans its environment and returns scan messages continuously.
* Mode 0: **continuous scanning**, the sensor scans its environment and returns scan messages continuously.
* Mode 1: **single scan**, the command triggers the sensor to scan only once and return the corresponding scan message.
> **Please note:**
> This command does not trigger an acknowlegment message. Its execution can be recognized by the scan message sent back following it by the sensor.
> **Please note:**
> This command does not trigger an acknowledgment message. Its execution can be recognized by the scan message sent back following it by the sensor.
| **Command** | **Description** | **Effect** | **Parameter** |**Applicable Values** | **Example** |
|-------------|-----------------|------------|---------------|----------------------|-------------|
......@@ -130,5 +130,4 @@ Structure for each command: `C` `<command>` `\r`
Connector shown from top view perspective:
![cable assignment](https://gitlab.com/toposens/public/resources/-/raw/master/2019-06_TS3_UART_cable_3.jpg)
![cable assignment](/TS3/Images/2019-06_TS3_UART_cable_3.jpg)
![Logo](/TS3/Images/logo2.png)
# TS3 - Known issues:
This document lists known issues and mitigations for TS3. If you encounter any issues not listed here, please contact [Toposens support](mailto:[email protected]).
## False positive detections due to high output power and/or low noise filtering
* **Description:** When operated under configurations involving _high output power_ (parameter "number of pulses" > 6) and/or _low noise filtering_ (parameter "echo rejection threshold" < 3, parameter "peak detection window" < 3), the sensor may show a few persistent erroneous points with a low relative volume.
* **Description:** When operated under configurations involving _high output power_ (parameter "number of pulses" > 6) and/or _low noise filtering_ (parameter "echo rejection threshold" < 3, parameter "peak detection window" < 3), the sensor may show a few persistent erroneous points with a low relative volume.
* **Mitigation:** Decreasing the parameter "number of pulses" and increasing parameters "echo rejection threshold" and "peak detection window".
\ No newline at end of file
* **Mitigation:** Decreasing the parameter "number of pulses" and increasing parameters "echo rejection threshold" and "peak detection window".
![Toposens](https://toposens.com/wp-content/themes/toposens/assets/img/logo2.png)
![Logo](/TS3/Images/logo2.png)
# TS3 setup guide - Ubuntu 16.04 and 18.04
This document guides you through setting up your TS3 on Ubuntu 16.04 (Xenial) or Ubuntu 18.04 (Bionic). Find all resources for TS3 on [GitLab](https://gitlab.com/toposens/public/resources/).
......@@ -11,13 +12,13 @@ Connect TS3 to your PC with the USB Mini-B cable:
1. Plug in the USB cable to TS3.
![Connect to TS3](http://toposens.com/wp-content/uploads/2019/11/ts3-setup-usb-connector.jpg)
![Connect to TS3](/TS3/Images/ts3-setup-usb-connector.jpg)
2. Plug in the USB cable to your PC.
![Connect to PC](http://toposens.com/wp-content/uploads/2019/11/ts3-setup-ubuntu.jpg)
![Connect to PC](/TS3/Images/ts3-setup-ubuntu.jpg)
**For TS3 v1.0 & v1.1:**
**For TS3 v1.0 & v1.1:**
Connect TS3 to your PC with the UART-to-USB-A cable:
1. Plug the UART-to-USB-A cable into the TS3.
......@@ -26,21 +27,21 @@ Connect TS3 to your PC with the UART-to-USB-A cable:
> When first plugged in, a green LED should briefly blink on the USB-A plug.
## Step 2: Obtain the connected terminal ID for TS3
## Step 2: Obtain the connected terminal ID for TS3
**For TS3 v1.2:**
Check which USB port the sensor is connected to:
`dmesg | grep "cp210x" | tail -n 1 | awk 'NF{print $NF}'`
In the case below, the terminal ID would be `ttyUSB0`:
![Obtain connected terminal ID](http://toposens.com/wp-content/uploads/2019/11/ttyPort.png)
![Obtain connected terminal ID](/TS3/Images/ttyPort.png)
**For TS3 v1.0 & v1.1:**
**For TS3 v1.0 & v1.1:**
Check which USB port the sensor is connected to:
`dmesg | grep "FTDI" | tail -n 1 | awk 'NF{print $NF}'`
......@@ -49,8 +50,8 @@ Check which USB port the sensor is connected to:
## Step 3: Read TS3 Data Stream in a Serial Terminal
Use GtkTerm (or your favorite serial port terminal) to communicate with your TS3:
1. Install GtkTerm:
1. Install GtkTerm:
`sudo apt-get install gtkterm`
......@@ -59,8 +60,8 @@ Use GtkTerm (or your favorite serial port terminal) to communicate with your TS3
`sudo adduser $USER dialout`
3. Reboot your system for updated permissions to take effect. If you don't want to reboot, use:
`newgrp dialout`
`newgrp dialout`
4. Connect TS3 to your PC as described in **Step 1: Connect TS3 to PC**
......@@ -69,22 +70,22 @@ Use GtkTerm (or your favorite serial port terminal) to communicate with your TS3
`gtkterm`
6. In GtkTerm, go to the *Configuration* tab to set up the serial communication:
* Set *Port* to the serial port of your TS3
* Set *Port* to the serial port of your TS3
* Set *Baud Rate* to `576000`
* Set *Parity* to `none`
* Set *Bits* to `8`
* Set *Stopbits* to `1`
* Click *OK*
> You can find out the serial port of your TS3 by following the instructions from **Step 2: Determine the Serial Port of TS3** of this guide.
> You can find out the serial port of your TS3 by following the instructions from **Step 2: Determine the Serial Port of TS3** of this guide.
![Use GtkTerm to commnuicate with TS3](http://toposens.com/wp-content/uploads/2019/09/ts3-gtkterm-576k-1.png)
![Use GtkTerm to commnuicate with TS3](/TS3/Images/ts3-gtkterm-576k-1.png)
7. You should now see the serial data stream of your TS3 in the terminal:
![Use GtkTerm to commnuicate with TS3](http://toposens.com/wp-content/uploads/2019/09/ts3-gtkterm-576k-2.png)
![Use GtkTerm to commnuicate with TS3](/TS3/Images/ts3-gtkterm-576k-2.png)
## Next Steps
* Now that you've got started with TS3, check out the **ROS packages** for Toposens sensors. Find instructions on the [ROS Wiki](http://wiki.ros.org/toposens).
* If you want to work with the raw data stream of TS3, check out our guide on the communication protocol of TS3 on [GitLab](https://gitlab.com/toposens/public/resources/blob/master/TS3/ts3-communication-protocol.md).
\ No newline at end of file
* If you want to work with the raw data stream of TS3, check out our guide on the communication protocol of TS3 on [GitLab](https://gitlab.com/toposens/public/resources/blob/master/TS3/ts3-communication-protocol.md).
![Toposens](https://toposens.com/wp-content/themes/toposens/assets/img/logo2.png)
![Logo](/TS3/Images/logo2.png)
# TS3 setup guide - Windows 10
This document guides you through setting up your TS3 on Windows 10. Find all resources for TS3 on [GitLab](https://gitlab.com/toposens/public/resources/).
......@@ -10,14 +11,14 @@ Connect TS3 to your PC with the USB Mini-B cable:
1. Plug in the USB cable to TS3.
![Connect to TS3](http://toposens.com/wp-content/uploads/2019/11/ts3-setup-usb-connector.jpg)
![Connect to TS3](/TS3/Images/ts3-setup-usb-connector.jpg)
2. Plug in the USB cable to your PC.
![Connect to PC](http://toposens.com/wp-content/uploads/2019/11/ts3-setup-w10.jpg)
![Connect to PC](/TS3/Images/ts3-setup-w10.jpg)
**For TS3 v1.0 & v1.1:**
**For TS3 v1.0 & v1.1:**
Connect TS3 to your PC with the UART-to-USB-A cable:
1. Plug the UART-to-USB-A cable into the TS3.
......@@ -26,7 +27,7 @@ Connect TS3 to your PC with the UART-to-USB-A cable:
> When first plugged in, a green LED should briefly blink on the USB-A plug.
## Step 2: Determine the COM Port of TS3
## Step 2: Determine the COM Port of TS3
1. Disconnect the USB cable (**for TS3 v1.0 & v1.1:** UART-to-USB-A cable) of your TS3 from your PC.
......@@ -38,35 +39,35 @@ Connect TS3 to your PC with the UART-to-USB-A cable:
4. With the Device Manager window open, connect TS3 to your PC as described in **Step 1: Connect TS3 to PC**. Look for a new entry in *Ports (COM & LPT)*: this is the COM port assigned to your TS3.
![Determine the COM Port of TS3](http://toposens.com/wp-content/uploads/2019/11/ts3-v12-device-manager-e1574269872851.png)
![Determine the COM Port of TS3](/TS3/Images/ts3-v12-device-manager-e1574269872851.png)
> **Please note:** If no driver is available for the device, it may be listed under *Other devices* instead of *Ports (COM & LPT)*, for example as *CP2102N USB to UART Bridge Controller* (for TS3 v1.2).
## Step 3: Read TS3 Data Stream in a Serial Terminal
Use RealTerm (or your favorite serial port terminal) to communicate with your TS3:
Use RealTerm (or your favorite serial port terminal) to communicate with your TS3:
1. Download and install [RealTerm](https://sourceforge.net/projects/realterm/).
2. Connect TS3 to your PC as described in **Step 1: Connect TS3 to PC**
3. Start RealTerm and go to the *Port* tab to set up the serial communication:
3. Start RealTerm and go to the *Port* tab to set up the serial communication:
* Set *Baud* to `576000`
* Set *Port* to the COM port of your TS3
* Set *Port* to the COM port of your TS3
* Set *Parity* to `None`
* Set *Data Bits* to `8 bits`
* Set *Stop Bits* to `1 bit`
* Click *Change* to apply changes
> You can find out the COM port of your TS3 by following the instructions from **Step 2: Determine the COM Port of TS3** of this guide.
> You can find out the COM port of your TS3 by following the instructions from **Step 2: Determine the COM Port of TS3** of this guide.
![Use RealTerm to commnuicate with TS3](http://toposens.com/wp-content/uploads/2019/09/ts3-realterm-576k-1.png)
![Use RealTerm to commnuicate with TS3](/TS3/Images/ts3-realterm-576k-1.png)
4. You should now see the serial data stream of your TS3 in the terminal:
![Use RealTerm to communicate with TS3](http://toposens.com/wp-content/uploads/2019/09/ts3-realterm-576k-2.png)
![Use RealTerm to communicate with TS3](/TS3/Images/ts3-realterm-576k-2.png)
## Next Steps
* Now that you've got started with TS3, check out the **ROS packages** for Toposens sensors. Find instructions on the [ROS Wiki](http://wiki.ros.org/toposens).
* If you want to work with the raw data stream of TS3, check out our guide on the communication protocol of TS3 on [GitLab](https://gitlab.com/toposens/public/resources/blob/master/TS3/ts3-communication-protocol.md).
\ No newline at end of file
* If you want to work with the raw data stream of TS3, check out our guide on the communication protocol of TS3 on [GitLab](https://gitlab.com/toposens/public/resources/blob/master/TS3/ts3-communication-protocol.md).
![Toposens](https://toposens.com/wp-content/themes/toposens/assets/img/logo2.png)
![Logo](/TS3/Images/logo2.png)
# TS3 Spec Sheet[^1]
This document lists the specifications for TS3[^2]. Find all resources for TS3 on [GitLab](https://gitlab.com/toposens/public/resources/).
......@@ -19,12 +20,12 @@ This document lists the specifications for TS3[^2]. Find all resources for TS3 o
| Target resolution[^5] | 3 cm |
[^3]: The exact ranges and angles, in which a specific target is detected, is dependent on target reflectivity and can be adapted by selecting different sensor parameters.<br>Sensor parameters used for testing: number of pulses = 8, echo rejection = 1, peak detection window = 1, 36 cm x 36 cm cardboard target
[^4]: Typical values are derived from tests under controlled conditions in an indoor environment with a standardized target (aluminium pole, diameter: 75 mm) at 1m distance. Actual values may vary due to environment conditions (e.g. airflow, temperature, humidity) and target reflectivity.<br>Sensor parameters used for testing: number of pulses = 5, echo rejection threshold = 3, peak detection window = 1
[^5]: Smallest difference in range between two targets for the sensor to be able to separate them into two signals / points. Targets in a smaller distance to each other can result in a merging signal returning a non-truthful angle measurement.
[^4]: Typical values are derived from tests under controlled conditions in an indoor environment with a standardized target (aluminium pole, diameter: 75 mm) at 1m distance. Actual values may vary due to environment conditions (e.g. airflow, temperature, humidity) and target reflectivity.<br>Sensor parameters used for testing: number of pulses = 5, echo rejection threshold = 3, peak detection window = 1
[^5]: Smallest difference in range between two targets for the sensor to be able to separate them into two signals / points. Targets in a smaller distance to each other can result in a merging signal returning a non-truthful angle measurement.
### Typical Detection Areas[^3]
![Typical Detection Areas](http://toposens.com/wp-content/uploads/2019/05/ts3-typical-detection-areas.png)
![Typical Detection Areas](/TS3/Images/ts3-typical-detection-areas.png)
### Known Issues
......@@ -32,7 +33,7 @@ Find descriptions of known issues of TS3 and their mitigations [here](https://gi
## Specifications - Technical
![TS3 drawing](http://toposens.com/wp-content/uploads/2019/11/TS3v12drawing.png)
![TS3 drawing](/TS3/Images/TS3v12drawing.png)
### Physical
......@@ -41,7 +42,7 @@ Find descriptions of known issues of TS3 and their mitigations [here](https://gi
| Size (L x W x H) | 71.4 x 27.5 x 11.1 mm |
| Weight | 20g |
| Operating temperature | -5° to 70°C |
### Electrical
| | |
......@@ -70,16 +71,19 @@ Find more information about the interface on [GitLab](https://gitlab.com/toposen
## Versions
### TS3 v1.0 (06/19)
![TS3 v1.0](http://toposens.com/wp-content/uploads/2019/10/ts3_v10.png) ![TS3 v1.0 side-view](http://toposens.com/wp-content/uploads/2019/11/ts3_v1_side.png)
![TS3 v1.0](/TS3/Images/ts3_v10.png)
![TS3 v1.0 side-view](/TS3/Images/ts3_v1_side.png)
### TS3 v1.1 (10/19)
![TS3 v1.1](http://toposens.com/wp-content/uploads/2019/10/ts3_v11.png) ![TS3 v1.1 side-view](http://toposens.com/wp-content/uploads/2019/11/ts3_v1_side.png)
#### Changes to previous version:
![TS3 v1.1](/TS3/Images/ts3_v11.png)
![TS3 v1.1 side-view](/TS3/Images/ts3_v1_side.png)
#### Changes to previous version:
* Adaption of housing and redesign of top layer PCB to improve manufacturability
* Change of components due to availability
### TS3 v1.2 (11/19):
![TS3 v1.2](http://toposens.com/wp-content/uploads/2019/11/ts3_v12.png) ![TS3 v1.2 side-view](http://toposens.com/wp-content/uploads/2019/11/ts3_v12_side.png)
![TS3 v1.2](/TS3/Images/ts3_v12.png)
![TS3 v1.2 side-view](/TS3/Images/ts3_v12_side.png)
#### Changes to previous version:
* Added USB Mini-B connector (not replacing Micro-Lock Plus connector (UART))
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment