SonaSoft Integration Examples

This repository is the examples home for integrating with SonaSoft. The general idea is that there are direct APIs you can use if you want more fine grained control, and SDKs available to get you started quickly.

Either way - to actually get data you will need either the SonaSoft SDK Demo running, or normal SonaSoft running connected to and an Argos sonar.

You can get the demo package by emailing us: sw@farsounder.com - it is available free of charge for development or academic purposes. There is a licensing fee per installation when you deploy your integration on customer vessels.

Start Here

If you want the easiest path to accessing data, start with the SDK examples:

• using_sdk/cpp/simple_example/
• using_sdk/python/simple_example/
• using_sdk/python/drawing_example/

If you want to integrate with the APIs directly for full control of receive threading, etc:

• direct_api/zmq_protobuf/cpp/
• direct_api/zmq_protobuf/python/
• Interactive Swagger docs at http://localhost:3000/docs when the SonaSoft demo is running

If you're having a problem with protobuf or zeromq and you want to test one piece at a time:

• reference/zmq_protobuf_basics/

Choosing A Path

Use The SDK

Use the SDK examples when you want the fastest route to request/reply calls and streaming data without owning the lower-level transport details yourself. They expose get/set functions for the request/reply calls - and let you register a callback to run on new data from the pub/sub streams.

For reference, the SDK clients themselves live in their own repos:

• C++ client: farsounder-cpp-client
• Python client: farsounder-python-client

Use The Direct APIs

SonaSoft exposes two direct APIs:

• Protobuf messages over ZeroMQ sockets
• JSON over HTTP or Websockets - eg a "REST" API

JSON over HTTP/Websocket is usually the easiest direct path just because it has become so common-place and most languages have some first class support for it. The ZeroMQ/Protobuf option makes sense for highest performance.

Other Clients

• The Technische Universität Berlin has created a ROS2 package for interfacing with SonaSoft™ via the ZeroMQ/Protobuf API. You can find it here

Simple ZMQ/Protobuf Reference Examples

The reference/ examples are intentionally small. They are meant to help you answer questions like:

• Is ZeroMQ installed and working?
• Is protobuf generation working?
• Can I do a minimal request/reply round trip?
• Can I receive a pub/sub message at all?

They are taken directly from the ZMQ and protobuf docs.

Comparison of Integration Options

Category	SDK Clients	HTTP / JSON	ZeroMQ / Protobuf
Best for	Fastest integration	Simple direct access	Lower-level direct access
Setup complexity	Lowest	Low	Highest
Transport details	Abstracted away	HTTP/Websocket	ZeroMQ sockets
Data format	Native client types	JSON	Protocol Buffers
Processor Controls	✅	✅	✅
Live seafloor detections	✅	✅	✅
Live in-water detections	✅	✅	✅
Gridded history data	✅	✅	❌
Hydrophone Timeseries Data	✅	❌	✅
Third Party Targets (Sea.AI, etc)	❌	✅	❌
SonaSoft LT Alarm Config	❌	✅	❌
Filtered NMEA Stream Data	❌	✅	❌

Notes

Note

In 4.2.x, the HTTP and ZeroMQ APIs are mutually exclusive. To use the Protobuf/ZeroMQ API on 4.2.x, remove the --http-nav-api launcher argument from the SDK package. In 4.3+ they can be run together.

If you have questions or need access to the SDK package, contact sw@farsounder.com.