Skip to content

Commit 331f528

Browse files
amarburgamarburg
authored
Update README.md
Major rewrite of the README.
1 parent 438f34a commit 331f528

File tree

1 file changed

+25
-46
lines changed

1 file changed

+25
-46
lines changed

‎README.md‎

Lines changed: 25 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -9,20 +9,18 @@ This library contains code for:
99

1010
- Communicating with a [Blueprint Subsea Oculus](https://www.blueprintsubsea.com/oculus/index.php) imaging sonar over
1111
its ethernet interface.
12-
13-
- Requesting that the sonar ping.
14-
12+
- Requesting that the sonar start pinging.
1513
- Decoding and parsing fields from the resulting ping messages from the sonar.
16-
1714
- Loading and parsing sonar data recorded as either:
1815
- Raw streams of binary packets.
19-
- Data encoded in the GPMF format by `serdp_recorder`
20-
- **Note:** This repo includes scaffold code for reading `.oculus` files saved from the Blueprint GUI, but as that format is proprietary and undocumented **we cannot actually parse `.oculus` files.**
16+
- **Note:** This repo includes scaffold code for reading `.oculus` files saved from the Blueprint GUI, but that format is proprietary and undocumented **we cannot parse `.oculus` files.**
2117

22-
The library contains no special provisions for _saving_ sonar data,
18+
The library contains no special provisions for *saving* sonar data,
2319
but it's straightforward to write packets as a raw binary stream
24-
(which the library can read) -- see `tools/oculus_client.cpp` for an example.
20+
(which the library can read) -- see [`tools/oculus_client.cpp`](https://github.com/apl-ocean-engineering/liboculus/blob/main/tools/oculus_client.cpp) for an example.
21+
2522

23+
---
2624
## Build/Installation
2725

2826
This is a hybrid repository:
@@ -42,19 +40,16 @@ binary `oc_client` requires [CLI11](https://github.com/CLIUtils/CLI11),
4240
both of which are also handled by fips.
4341

4442
Internally, the ethernet interface uses
45-
[Boost::asio](https://www.boost.org/doc/libs/1_66_0/doc/html/boost_asio.html),
46-
so Boost needs to be installed.
47-
48-
43+
[Boost::asio](https://www.boost.org/doc/libs/1_66_0/doc/html/boost_asio.html).
4944

45+
---
5046
## oc_client binary
5147

5248
The repo contains one binary, `oc_client` which can read data either from a
5349
real Oculus sonar via ethernet, or from a file containing raw Ethernet
5450
data.
5551

56-
As noted above, it **cannot** read
57-
files saved by the proprietary Oculus GUI as that receives data from the sonar in a proprietary data format (independent from the `SimplePingResult` format used in this code).
52+
As noted above, it **cannot** read files saved by the proprietary Oculus GUI as that is based on a proprietary data format (independent from the `SimplePingResult` format used in this code).
5853

5954
Here's the help string for `oc_client`:
6055

@@ -76,40 +71,16 @@ streams of sonar packets, and can be opened by `oc_client`.
7671

7772
## Library Design
7873

79-
The driver using this library is expected to instantiate a SonarClient, and hook up two interfaces:
80-
1. Instantiate a SonarConfig that will be kept updated with desired parameters; the SonarClient takes this as an argument at construction and keeps a reference to it.
81-
1. implement a callback that will handle data received from the sensor.
82-
83-
Thus, the data flow is:
84-
* Updating configuration:
85-
- Driver decides configuration needs to be updated. In the case of `oculus_sonar_driver`, this is triggered by `dynamic_reconfigure`. Driver calls `SonarConfiguration::.set{Range,etc.}`. Driver *owns* an instance of SonarConfig.
86-
- When updated, `SonarConfig` has a pointer to a callback that it calls, passing a pointer to itself.
87-
- That configCallback is responsible for actually sending it to the instrument. This is done by DataRx::sendConfiguration.
88-
* Receiving
89-
- DataRx listens on the specified port. The message is read in two chunks, by `DataRx::readHeader` and `DataRx::readSimplePingResult`. The second of those stuffs the data into a `SimplePingResult` (which in turn is a thin wrapper around the Oculus-defined struct) and calls the provided callback.
90-
- This callback was set by ...
91-
92-
* Receiving status
93-
- StatusRx
94-
95-
The SonarClient itself owns a StatusRx and a DataRx, each of which listens on a fixed port for the given messages.
96-
* The StatusRx callback simply prints warnings, and attempts to connect the DataRx using the received address.
97-
* The DataRx
98-
99-
100-
The SonarConfiguration is really obnoxious:
101-
* the oculus_driver owns it.
102-
* SonarClient is constructed with a config and keeps a reference
103-
* SonarClient passes the reference to DataRx
104-
* DataRx sets the callback that causes ges from the oculus_driver to actually be sent to the instrument.
74+
See [oc_client](https://github.com/apl-ocean-engineering/liboculus/blob/main/tools/oculus_client.cpp) as a sample non-ROS client. A typical client will have instances of two interface classes. Both use Boost::Asio for network IO and must be given an [`boost::asio::io_context`](https://www.boost.org/doc/libs/1_79_0/doc/html/boost_asio/reference/io_context.html) on construction.
10575

76+
* [DataRx](https://github.com/apl-ocean-engineering/liboculus/blob/main/include/liboculus/DataRx.h) receives packets from the sonar, calling a callback function for each ping.
77+
* [StatusRx](https://github.com/apl-ocean-engineering/liboculus/blob/main/include/liboculus/StatusRx.h) monitors the UDP broadcast-based protocol used to autodetect sonars on the network. On receiving a good sonar status, it calls a callback.
10678

79+
The client must implement callbacks that will handle data from the sonar ([for example](https://github.com/apl-ocean-engineering/liboculus/blob/438f34a469eaf0d495ea515e86290b39cf965a20/tools/oculus_client.cpp#L131)) -- independent callbacks must be defined for the Oculus V1 and V2 packets. DataRx also has a [callback on successful connection with a sonar](https://github.com/apl-ocean-engineering/liboculus/blob/438f34a469eaf0d495ea515e86290b39cf965a20/tools/oculus_client.cpp#L181) which can be used to send a configuration to the sonar (this will start the sonar pinging).
10780

10881
This library makes liberal use of overlay classes in order to provide
10982
zero-copy accessor functions into the raw data chunks received from
110-
the oculus.
111-
112-
These classes overlay the struct hierarchy defined in
83+
the oculus. These classes overlay the struct hierarchy defined in
11384
thirdparty/Oculus/Oculus.h, making it possible to directly cast between the types depending on which accessors you want to use:
11485
* OculusSimplePingResult carries all image data from the oculus.
11586
* Its first field is the OculusSimpleFireMessage that triggered data collection
@@ -133,11 +104,19 @@ Other files/classes:
133104
* StatusRx: Connects to the fixed status port; stuffs messages into a SonarStatus and calls SonarClient's callback with the SonarStatus.
134105
* SonarStatus: Wrapper around OculusStatusMsg. Only used to dump it to LOG(DEBUG), so I'd like to see it disappear in favor of a log_status helper function.
135106

136-
* IoServiceThread: thin wrapper around boost::asio functions providing a simple worker thread; used by both StatusRx and DataRx
107+
* IoServiceThread: thin wrapper which runs a [`boost::asio::io_context`](https://www.boost.org/doc/libs/1_79_0/doc/html/boost_asio/reference/io_context.html) within a thread. Used by both StatusRx and DataRx
108+
109+
----
110+
# Related Packages
137111

112+
* [sonar_image_proc](https://github.com/apl-ocean-engineering/sonar_image_proc) contains code to postprocess sonar data, including drawing the sonar data to an OpenCV Mat (contains both a ROS node and non-ROS library).
113+
* [oculus_sonar_driver](https://gitlab.com/apl-ocean-engineering/oculus_sonar_driver) provides a ROS node for interfacing with the Oculus sonar.
114+
* [acoustic_msgs](https://github.com/apl-ocean-engineering/hydrographic_msgs/tree/main/acoustic_msgs) defines the ROS [SonarImage](https://github.com/apl-ocean-engineering/hydrographic_msgs/blob/main/acoustic_msgs/msg/SonarImage.msg) message type published by [oculus_sonar_driver](https://gitlab.com/apl-ocean-engineering/oculus_sonar_driver).
115+
* [rqt_sonar_image_view](https://github.com/apl-ocean-engineering/rqt_sonar_image_view) is an Rqt plugin for displaying sonar imagery (uses [sonar_image_proc](https://github.com/apl-ocean-engineering/sonar_image_proc))
138116

139-
## License
117+
---
118+
# License
140119

141120
This code is released under the [BSD 3-clause license](LICENSE).
142121

143-
This repository contains one file provided by Blueprint as part of their free "Oculus Viewer" sample application ([thirdparty/Oculus/Oculus.h](thirdpart/Oculus/Oculus.h)), which describes their protocol and data formats. This file is distributed under [GPLv3](https://www.gnu.org/licenses/gpl-3.0.en.html).
122+
This repository contains one file provided by Blueprint as part of their free "Oculus Viewer" sample application ([thirdparty/Oculus/Oculus.h](thirdpart/Oculus/Oculus.h)), which describes their protocol and data formats. This file is distributed under [GPLv3](https://www.gnu.org/licenses/gpl-3.0.en.html).

0 commit comments

Comments
 (0)