Skip to content

GitLab

Home · Changes

Page history
Update home authored by Wouter Jansen's avatar Wouter Jansen
Hide whitespace changes
Inline Side-by-side
home.md
View page @ 831c0fa6
# **RTIS Common Documentation - Table of Content** # **RTIS Common Documentation - Table of Content**
- [General Usage](#general-usage)
- [Classes](#classes) - [Classes](#classes)
- [RTISClientObj](#rtisclientobj) - [RTISClientObj](#rtisclientobj)
- [Pose](#pose) - [Pose](#pose)
...@@ -13,65 +12,12 @@ ...@@ -13,65 +12,12 @@
- [set_behaviour_active](#set_behaviour_active) - [set_behaviour_active](#set_behaviour_active)
- [set_behaviour_passive](#set_behaviour_passive) - [set_behaviour_passive](#set_behaviour_passive)
# **General Usage**
This is a library used by most parts of the RTIS Network including the CLients, Server and applications.
This documentation is mostly meant to explain how to use it to create your own applications.
Making a new application for the RTIS Network is rather straight forward.
Several functions are available to be used to gain information on the connected
RTIS Clients and Server and prepare your application for their data.
All the available commands are explained below.
For receiving the measurement data one should set up a TCP socket server with the
IP defined in the [serversettings.json](Config/serversettings.json) as _applicationIp_ with port `65444`.
For example:
```python
import socket
import pickle
serverSocket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
serverSocket.bind(('applicationIp', 65444))
serverSocket.listen(10)
print("Started data listener.")
while True:
try:
conn, address = serverSocket.accept()
data = []
while True:
packet = conn.recv(2048)
if not packet: break
data.append(packet)
dataPackage = pickle.loads(b"".join(data))
print("measurement #" + dataPackage[4] + " received!")
except socket.error as ex:
print("the RTIS Server aborted the data connection: " + str(ex))
except pickle.UnpicklingError as ex:
print("the RTIS Server aborted the data connection: " + str(ex))
except EOFError as ex:
print("The RTIS Server aborted the data connection: " + str(ex))
except KeyboardInterrupt:
print("Closing data listener...")
serverSocket.close()
```
The `dataPackage` that the RTIS Network Server sends contains a tuple with the following elements in this order:
- `ID`: string: The RTIS Client ID.
- `processedData`: numpy ndarray: The data matrix holding the optionally processed data.
- `rawData`: numpy ndarray: The data matrix holding the raw recording data samples as uint32.
- `timestamp`: float: Epoch timestamp of when the measurement was taken on the RTIS Client.
- `index`: int: The measurement index of this measurement for this RTIS Client.
- `behaviour`: int (0 or 1): The behaviour of the RTIS Client sonar mode. 0 means passive, 1 means active.
# **Classes** # **Classes**
## **RTISClientObj** ## **RTISClientObj**
<p class="func-header"> <p class="func-header">
<i>class</i> <b>RTISClientObj</b>(<i>client_id, client_ip, network_version, firmware_version, required, client_online=True</i>) <a class="src-href" target="_blank" href="https://cosysgit.uantwerpen.be/rtis-software/rtiscommon/-/blob/master/RTISCommon.py#L83">[source]</a> <i>class</i> <b>RTISClientObj</b>(<i>client_id, client_ip, network_version, firmware_version, required, client_online=True</i>) <a class="src-href" target="_blank" href="https://cosysgit.uantwerpen.be/rtis-software/rtiscommon/-/blob/master/RTISCommon.py#L81">[source]</a>
</p> </p>
Class describing a connected RTIS Client. Class describing a connected RTIS Client.
...@@ -94,7 +40,7 @@ Class describing a connected RTIS Client. ...@@ -94,7 +40,7 @@ Class describing a connected RTIS Client.
<p class="attr"> <p class="attr">
If the RTIS Client has timed out it will be set to False, otherwise it will always be True. If the RTIS Client has timed out it will be set to False, otherwise it will always be True.
</p> </p>
<b>lastHeartBeatTimestamp : <i>datetime datetime</i></b> <b>lastHeartbeatTimestamp : <i>datetime.datetime</i></b>
<p class="attr"> <p class="attr">
The datetime object telling the last time a heartbeat was received from an RTIS Client. The datetime object telling the last time a heartbeat was received from an RTIS Client.
</p> </p>
...@@ -114,7 +60,7 @@ Class describing a connected RTIS Client. ...@@ -114,7 +60,7 @@ Class describing a connected RTIS Client.
<p class="attr"> <p class="attr">
A state indicator to know if the sensor has been in the 'Ready' state for at least 1 minute to indicate it is fully ready and stable for operation. 0 = not stable yet | 1 = stable A state indicator to know if the sensor has been in the 'Ready' state for at least 1 minute to indicate it is fully ready and stable for operation. 0 = not stable yet | 1 = stable
</p> </p>
<b>startStableTimestamp : <i>datetime datetime</i></b> <b>startStableTimestamp : <i>datetime.datetime</i></b>
<p class="attr"> <p class="attr">
The datetime object telling the start time the RTIS Client was in the 'Ready' state. The datetime object telling the start time the RTIS Client was in the 'Ready' state.
</p> </p>
...@@ -149,7 +95,7 @@ Class describing a connected RTIS Client. ...@@ -149,7 +95,7 @@ Class describing a connected RTIS Client.
<p class="func-header"> <p class="func-header">
<i></i> <b>update_heartbeat</b>(<i>self, client_ip, client_configured, client_behaviour, client_inputDataQueueSize, client_outputDataQueueSize, client_internalCounter</i>) <a class="src-href" target="_blank" href="https://cosysgit.uantwerpen.be/rtis-software/rtiscommon/-/blob/master/RTISCommon.py#L190">[source]</a> <i></i> <b>update_heartbeat</b>(<i>self, client_ip, client_configured, client_behaviour, client_inputDataQueueSize, client_outputDataQueueSize, client_internalCounter</i>) <a class="src-href" target="_blank" href="https://cosysgit.uantwerpen.be/rtis-software/rtiscommon/-/blob/master/RTISCommon.py#L188">[source]</a>
</p> </p>
Method that is used by RTIS Server to update the status of a RTIS Client when a new heartbeat is received. Method that is used by RTIS Server to update the status of a RTIS Client when a new heartbeat is received.
...@@ -193,10 +139,10 @@ Method that is used by RTIS Server to update the status of a RTIS Client when a ...@@ -193,10 +139,10 @@ Method that is used by RTIS Server to update the status of a RTIS Client when a
<p class="func-header"> <p class="func-header">
<i></i> <b>check_heartbeat</b>(<i>self, maximum_delta=15</i>) <a class="src-href" target="_blank" href="https://cosysgit.uantwerpen.be/rtis-software/rtiscommon/-/blob/master/RTISCommon.py#L226">[source]</a> <i></i> <b>check_heartbeat</b>(<i>self, maximum_delta=15</i>) <a class="src-href" target="_blank" href="https://cosysgit.uantwerpen.be/rtis-software/rtiscommon/-/blob/master/RTISCommon.py#L224">[source]</a>
</p> </p>
Method to check if a RTIS Client has timed out based on a check of it's previous received heartbeat. Method to check if a RTIS Client has timed out based on a check if it is previous received heartbeat.
<table class="docutils field-list field-table" frame="void" rules="none"> <table class="docutils field-list field-table" frame="void" rules="none">
<col class="field-name" /> <col class="field-name" />
...@@ -224,7 +170,7 @@ Method to check if a RTIS Client has timed out based on a check of it's previous ...@@ -224,7 +170,7 @@ Method to check if a RTIS Client has timed out based on a check of it's previous
<p class="func-header"> <p class="func-header">
<i></i> <b>check_stability</b>(<i>self</i>) <a class="src-href" target="_blank" href="https://cosysgit.uantwerpen.be/rtis-software/rtiscommon/-/blob/master/RTISCommon.py#L249">[source]</a> <i></i> <b>check_stability</b>(<i>self</i>) <a class="src-href" target="_blank" href="https://cosysgit.uantwerpen.be/rtis-software/rtiscommon/-/blob/master/RTISCommon.py#L247">[source]</a>
</p> </p>
Method to check if a RTIS Client is in the 'ready' configuration state for at least 1 minute Method to check if a RTIS Client is in the 'ready' configuration state for at least 1 minute
...@@ -249,11 +195,11 @@ to indicate it is fully ready and stable for operation. ...@@ -249,11 +195,11 @@ to indicate it is fully ready and stable for operation.
## **Pose** ## **Pose**
<p class="func-header"> <p class="func-header">
<i>class</i> <b>Pose</b>(<i>x, y, z, pitch, yaw, roll</i>) <a class="src-href" target="_blank" href="https://cosysgit.uantwerpen.be/rtis-software/rtiscommon/-/blob/master/RTISCommon.py#L278">[source]</a> <i>class</i> <b>Pose</b>(<i>x, y, z, pitch, yaw, roll</i>) <a class="src-href" target="_blank" href="https://cosysgit.uantwerpen.be/rtis-software/rtiscommon/-/blob/master/RTISCommon.py#L276">[source]</a>
</p> </p>
Class describing a 3D pose using the right-handed coordinate system where x points forward, Y points to the left Class describing a 3D pose using the right-handed coordinate system where x points forward, Y points to the left
and Z point upwards. Rotations are around these axis also by the right-hand rule with roll being and Z point upwards. Rotations are around these axes also by the right-hand rule with roll being
around the X-axis, pitch being around the Y-axis and yaw around the Z-axis. around the X-axis, pitch being around the Y-axis and yaw around the Z-axis.
x, y and z are in meters. Pitch, yaw and roll in degrees. x, y and z are in meters. Pitch, yaw and roll in degrees.
...@@ -298,7 +244,7 @@ x, y and z are in meters. Pitch, yaw and roll in degrees. ...@@ -298,7 +244,7 @@ x, y and z are in meters. Pitch, yaw and roll in degrees.
## **dspSettings** ## **dspSettings**
<p class="func-header"> <p class="func-header">
<i>class</i> <b>dspSettings</b>(<i>configName, dspFiles, workers, pdmEnable, matchedFilterEnable, beamformingEnable, enveloppeEnable, cleanEnable, version</i>) <a class="src-href" target="_blank" href="https://cosysgit.uantwerpen.be/rtis-software/rtiscommon/-/blob/master/RTISCommon.py#L348">[source]</a> <i>class</i> <b>dspSettings</b>(<i>configName, dspFiles, workers, pdmEnable, matchedFilterEnable, beamformingEnable, enveloppeEnable, cleanEnable, version</i>) <a class="src-href" target="_blank" href="https://cosysgit.uantwerpen.be/rtis-software/rtiscommon/-/blob/master/RTISCommon.py#L346">[source]</a>
</p> </p>
Class describing all the recording and processing settings related to RTIS devices. Class describing all the recording and processing settings related to RTIS devices.
...@@ -322,14 +268,14 @@ Can be converted to a dictionary. ...@@ -322,14 +268,14 @@ Can be converted to a dictionary.
## **dsp_worker_process** ## **dsp_worker_process**
<p class="func-header"> <p class="func-header">
<i>def</i> <b>dsp_worker_process</b>(<i>dspSettings, inputDataQueue, outputDataQueue, logger =None</i>) <a class="src-href" target="_blank" href="https://cosysgit.uantwerpen.be/rtis-software/rtiscommon/-/blob/master/RTISCommon.py#L509">[source]</a> <i>def</i> <b>dsp_worker_process</b>(<i>dspSettings, inputDataQueue, outputDataQueue, logger =None</i>) <a class="src-href" target="_blank" href="https://cosysgit.uantwerpen.be/rtis-software/rtiscommon/-/blob/master/RTISCommon.py#L508">[source]</a>
</p> </p>
The method to use als a `multiprocessing.Process` to perform a DSP pipeline on sonar measurements The method to use als a `multiprocessing.Process` to perform a DSP pipeline on sonar measurements
using the RTIS CUDA library. This will run continiously until closed. using the RTIS CUDA library. This will run continuously until closed.
It will first prepare the DSP pipeline with the given settings. Afterwards it will process each measurement It will first prepare the DSP pipeline with the given settings. Afterwards it will process each measurement
placed on the input data queue and place the result on the output data queue. placed on the input data queue and place the result on the output data queue.
This method should only be used the the RTIS Server and not by applications. This method should only be used the RTIS Server and not by applications.
The resulting data on the output data queue will be a tuple with the following content: The resulting data on the output data queue will be a tuple with the following content:
- `ID`: string: The RTIS Client ID. - `ID`: string: The RTIS Client ID.
...@@ -370,11 +316,11 @@ The resulting data on the output data queue will be a tuple with the following c ...@@ -370,11 +316,11 @@ The resulting data on the output data queue will be a tuple with the following c
## **get_server_config** ## **get_server_config**
<p class="func-header"> <p class="func-header">
<i>def</i> <b>get_server_config</b>(<i>serverIp, logger=None</i>) <a class="src-href" target="_blank" href="https://cosysgit.uantwerpen.be/rtis-software/rtiscommon/-/blob/master/RTISCommon.py#L580">[source]</a> <i>def</i> <b>get_server_config</b>(<i>serverIp, logger=None</i>) <a class="src-href" target="_blank" href="https://cosysgit.uantwerpen.be/rtis-software/rtiscommon/-/blob/master/RTISCommon.py#L604">[source]</a>
</p> </p>
A method to connect to the RTIS Server and get the [`dspSettings`](https://cosysgit.uantwerpen.be/rtis-software/rtiscommon/-/wikis/home#dspsettings) currently used by the RTIS Server. A method to connect to the RTIS Server and get the [`dspSettings`](https://cosysgit.uantwerpen.be/rtis-software/rtiscommon/-/wikis/home#dspsettings) currently used by the RTIS Server.
Usefull for connected applications. Useful for connected applications.
<table class="docutils field-list field-table" frame="void" rules="none"> <table class="docutils field-list field-table" frame="void" rules="none">
<col class="field-name" /> <col class="field-name" />
...@@ -406,12 +352,12 @@ Usefull for connected applications. ...@@ -406,12 +352,12 @@ Usefull for connected applications.
## **get_clients_and_configs** ## **get_clients_and_configs**
<p class="func-header"> <p class="func-header">
<i>def</i> <b>get_clients_and_configs</b>(<i>serverIp, logger=None</i>) <a class="src-href" target="_blank" href="https://cosysgit.uantwerpen.be/rtis-software/rtiscommon/-/blob/master/RTISCommon.py#L656">[source]</a> <i>def</i> <b>get_clients_and_configs</b>(<i>serverIp, logger=None</i>) <a class="src-href" target="_blank" href="https://cosysgit.uantwerpen.be/rtis-software/rtiscommon/-/blob/master/RTISCommon.py#L681">[source]</a>
</p> </p>
A method to connect to the RTIS Server and get all the active connected RTIS Clients A method to connect to the RTIS Server and get all the active connected RTIS Clients
with and their respective [`dspSettings`](https://cosysgit.uantwerpen.be/rtis-software/rtiscommon/-/wikis/home#dspsettings). with and their respective [`dspSettings`](https://cosysgit.uantwerpen.be/rtis-software/rtiscommon/-/wikis/home#dspsettings).
Usefull for connected applications. Useful for connected applications.
<table class="docutils field-list field-table" frame="void" rules="none"> <table class="docutils field-list field-table" frame="void" rules="none">
<col class="field-name" /> <col class="field-name" />
...@@ -443,11 +389,11 @@ Usefull for connected applications. ...@@ -443,11 +389,11 @@ Usefull for connected applications.
## **get_client_pose** ## **get_client_pose**
<p class="func-header"> <p class="func-header">
<i>def</i> <b>get_client_pose</b>(<i>serverIp, client_id, logger=None</i>) <a class="src-href" target="_blank" href="https://cosysgit.uantwerpen.be/rtis-software/rtiscommon/-/blob/master/RTISCommon.py#L752">[source]</a> <i>def</i> <b>get_client_pose</b>(<i>serverIp, client_id, logger=None</i>) <a class="src-href" target="_blank" href="https://cosysgit.uantwerpen.be/rtis-software/rtiscommon/-/blob/master/RTISCommon.py#L778">[source]</a>
</p> </p>
A method to connect to the RTIS Server and get the [`Pose`](https://cosysgit.uantwerpen.be/rtis-software/rtiscommon/-/wikis/home#pose) of a particular RTIS Client with. A method to connect to the RTIS Server and get the [`Pose`](https://cosysgit.uantwerpen.be/rtis-software/rtiscommon/-/wikis/home#pose) of a particular RTIS Client with.
Usefull for connected applications. Useful for connected applications.
<table class="docutils field-list field-table" frame="void" rules="none"> <table class="docutils field-list field-table" frame="void" rules="none">
<col class="field-name" /> <col class="field-name" />
...@@ -483,11 +429,11 @@ Usefull for connected applications. ...@@ -483,11 +429,11 @@ Usefull for connected applications.
## **set_behaviour_active** ## **set_behaviour_active**
<p class="func-header"> <p class="func-header">
<i>def</i> <b>set_behaviour_active</b>(<i>serverIp, logger=None</i>) <a class="src-href" target="_blank" href="https://cosysgit.uantwerpen.be/rtis-software/rtiscommon/-/blob/master/RTISCommon.py#L801">[source]</a> <i>def</i> <b>set_behaviour_active</b>(<i>serverIp, logger=None</i>) <a class="src-href" target="_blank" href="https://cosysgit.uantwerpen.be/rtis-software/rtiscommon/-/blob/master/RTISCommon.py#L827">[source]</a>
</p> </p>
A method to connect to the RTIS Server tell all connected RTIS Clients to set their sonar behaviour to active. A method to connect to the RTIS Server tell all connected RTIS Clients to set their sonar behaviour to active.
Usefull for connected applications. Useful for connected applications.
<table class="docutils field-list field-table" frame="void" rules="none"> <table class="docutils field-list field-table" frame="void" rules="none">
<col class="field-name" /> <col class="field-name" />
...@@ -512,11 +458,11 @@ Usefull for connected applications. ...@@ -512,11 +458,11 @@ Usefull for connected applications.
## **set_behaviour_passive** ## **set_behaviour_passive**
<p class="func-header"> <p class="func-header">
<i>def</i> <b>set_behaviour_passive</b>(<i>serverIp, logger=None</i>) <a class="src-href" target="_blank" href="https://cosysgit.uantwerpen.be/rtis-software/rtiscommon/-/blob/master/RTISCommon.py#L828">[source]</a> <i>def</i> <b>set_behaviour_passive</b>(<i>serverIp, logger=None</i>) <a class="src-href" target="_blank" href="https://cosysgit.uantwerpen.be/rtis-software/rtiscommon/-/blob/master/RTISCommon.py#L854">[source]</a>
</p> </p>
A method to connect to the RTIS Server tell all connected RTIS Clients to set their sonar behaviour to passive. A method to connect to the RTIS Server tell all connected RTIS Clients to set their sonar behaviour to passive.
Usefull for connected applications. Useful for connected applications.
<table class="docutils field-list field-table" frame="void" rules="none"> <table class="docutils field-list field-table" frame="void" rules="none">
<col class="field-name" /> <col class="field-name" />
...@@ -534,4 +480,5 @@ Usefull for connected applications. ...@@ -534,4 +480,5 @@ Usefull for connected applications.
</p></td> </p></td>
</tr> </tr>
</tbody> </tbody>
</table> </table>
\ No newline at end of file