M3 Sonar API
Instruction Manual
Release 1.4

This manual provides the basic information required to get started with the M3 Sonar API.

922-20007052/1.4
April 2024 © Kongsberg Maritime AS


About this manual
This manual provides the information and procedures required to use the M3 Sonar API.
Target audience
This publication is intended for all users of the M3 Sonar system.
A good understanding of system functions and controls is essential to fully take advantage of the functionality provided. A careful study of the information in this manual is highly recommended, preferably while exploring the functionality offered by the M3 Sonar system.
We assume that you are familiar with the basic setup and operation of the M3 Sonar. We also expect that you have some experience with sonar operation.
License information
The M3 Software is included with the M3 Sonar system and updates are available free of charge.
Software version
This M3 Sonar Instruction Manual complies with M3 software version 2.5.4.
Registered trademarks
Observe the registered trademarks that apply.
Windows® is a registered trademark of Microsoft Corporation in the United States and other countries.
M3 Sonar® is a registered trademark of Kongsberg Discovery Canada Ltd. in the United States and other countries.
We want your feedback
We always want to improve our products. We also want our end-user documentation to be comprehensive and relevant. You can help. Please provide comments, suggestions or constructive criticism to our support office. You can contact us by phone at +1 604 464 8144, or by email at: support.vancouver@kd.kongsberg.com.


M3 Sonar
Topics
System description
System diagram
M3 Sonar API overview
System units
Support information


System description
The Kongsberg Discovery M3 Sonar is a compact, versatile multibeam sonar.
Multibeam sonars have an array of transducers that simultaneously transmits pings (sound pulses) at a specified frequency to cover a large area in less time than a single-beam transducer. To generate data, computer software assigns a colour range corresponding to the amount of sound reflected off a target. The distance to the target is determined by the length of time it took to receive the transmitted acoustic pulse.
By combining the high refresh rate of a conventional multibeam sonar with an image quality comparable to a single-beam sonar, the M3 Sonar provides high-resolution images that are easy to interpret. The M3 Sonar detects objects out to 150 metres and has a 120° to 140° field of view, allowing you to see the full underwater picture in real-time.
The M3 Sonar provides wide-angle full-range situational awareness and concurrent ultra-short range imaging with dynamic focusing. For optimized obstacle avoidance, the M3 Sonar uses variable vertical beamwidth.


System diagram
The system diagram identifies the main components of a basic M3 Sonar system. Only the main connections between the units are shown. Detailed interface capabilities and power cables are not shown.
A Sonar Processor
B Power supply
C M3 Sonar Head


M3 Sonar API overview
The M3 Sonar API allows you to control the M3 Sonar via remote TCP/IP commands and without the graphical user interface.
When the API is enabled, you can use your custom application (TCP client) to issue commands to the sonar. You can write API commands in XML format.
The Command-Server Object listens on a port for TCP/IP commands issued by your application. When the Command-Server Object receives commands, it will send the commands to a Command-Processor Object, which process the commands and makes the appropriate function calls. The Command-Server Object replies with a response string that is received by your TCP client. You can read these responses to understand the result of the last API command sent to the server.
You can use the API Testing software to test the M3 Sonar API functionality. You can also use the Database Editor software to view or edit all the sonar applications (operational modes) available for the sonar.
The M3 Sonar API is enabled through the Windows command prompt. For imaging applications where low CPU usage is required, you can disable the Display Manager with a command-prompt switch.
To start the API automatically when your computer boots up, you can create a batch file containing the command-prompt text suitable for your application. If you have more than one Sonar Head, it is possible to run multiple instances of the API.
IMB data is streamed automatically every time your TCP client connects to the IMB port of the M3 Sonar API. You can also stream ALL data by issuing API commands to start and stop the data export. ALL data can be exported to third-party software, such as Hypack.


System units
Topics
Sonar Processor
Power supply
Sonar Head


Sonar Processor
In this publication, the computer can also be referred to as the Processor Unit, and vice versa. The Sonar Processor contains the operational software, and offers the user interface that allows you to control the M3 Sonar. It is a vital part of the M3 Sonar system.
The Sonar Processor runs the M3 software that manages communication with the Sonar Head, performs all beamforming and image processing and presents the sonar imagery. The Sonar Processor communicates with the sonar through a standard Ethernet cable.
If you purchase a computer locally, make sure that the chosen model meets the functional and technical requirements. The computer must be designed for rugged use. The construction must be able to withstand the vibrations and movements of a vessel.


Power supply
The Sonar Head requires a DC power supply to run.
Normally, the DC voltage is supplied in the location where the Sonar Head is mounted, such as on a remotely operated vehicle (ROV). A small DC switching supply can be used when running the system on a surface vessel.
A test cable and power supply is available for order as an accessory. The test power supply uses a 24 VDC switching power supply.


Sonar Head
When deployed underwater, the Sonar Head transmits and receives acoustic pulses.
The Sonar Head includes transmit and receive transducers and the electronics to generate the transmit pulse and digitize the received signal. The sonar data is sent to the Sonar Processor using a standard Ethernet link.
Note
The Sonar Head’s black polyurethane transducer is delicate. Always keep the Guard Ring and protective cover over the transducer during installation and storage.
Several different M3 Sonar models are available – your model may differ from the one shown here. For example, there are models with different depth ratings and materials, as well as models that include an integrated sound velocity sensor or high-frequency transducer.


Support information
If you need technical support for your M3 Sonar you must contact your local dealer, or our support department.
If you require maintenance or repair, contact your local dealer. You can contact us by phone at +1 604 464 8144, or by email at: support.vancouver@kd.kongsberg.com. If you need information about our other products, visit https://www.kongsberg.com/discovery/. On our website you will also find a list of our dealers and distributors.


Getting started
Topics
Setting the Sonar Processor to High Performance
Installing the M3 software
Defining the IP address on the computer's network adapter
Changing the Windows regional format to English
Starting operation of the Sonar Head
Enabling the M3 Sonar API
Disabling the M3 Sonar API


Operating procedures
Topics
Testing the M3 Sonar API
Finding a mode number
Changing the IMB port number
Streaming ALL data for profiling applications
Running more than one Sonar Head
Automatically enabling the M3 Sonar API at bootup


Functions and dialog boxes
Topics
API functions
API responses
Data streaming
API Testing software


API functions
Topics
M3 Sonar API overview
Connect
Disconnect
Get Status
Set Mode
Set TVG
Stop Ping
Start Ping
Start Record
Stop Record
Start Export
Stop Export
Frequency


M3 Sonar API overview
You can write API commands in XML format.
Description
You can write any API command in either a string or byte array in ASCII through your TCP client. The commands require a newline character after each node.
If you are using the API Testing software, then you can write an XML test script file with a list of commands that are executed sequentially.
For every XML string successfully sent to the server, the host TCP server will issue a response string to be received by the TCP client. You can read these responses to understand the result of the last API command sent to the server.


Connect
The Connect function establishes communication between the M3 software and Sonar Head, then starts “pinging”.
Description
In the M3 software, clicking Setup→Connect enables the Connect function.
Details
Connect API
<Command>
<Operation>Connect</Operation>
</Command>


Disconnect
The Disconnect function stops operation of the Sonar Head.
Description
In the M3 software, clicking Setup→Disconnect performs this function.
This function only works if the Sonar Head is running. Attempting to execute this command when the Sonar Head is not running will elicit a FAIL response.
Details
Disconnect API
<Command>
<Operation>Disconnect</Operation>
</Command>


Get Status
The Get Status function displays information about the Sonar Head and M3 software in the API response text.
Description
There is no equivalent to this function in the M3 software.
This command will return the Sonar Head status (Pinging, Connected, or Not Connected) as well as the M3 software version number.
Note
The <Status> tag shown in API responses is not related to the Get Status function.
Details
Get Status API
<Command>
<Operation>Get_Status</Operation>
</Command>
Get Status API response
<Response>
<Operation>Get_Status</Operation>
<Status>OK</Status>
<Message>Pinging</Message>
<Version>2.1.0</Version>
<Time>2016-09-13 15:22:21</Time>
</Response>


Set Mode
The Set Mode function allows you to set the optimal operating mode for your application. Each mode has its own pre-defined characteristics, such as differing ranges, angular resolutions, and pulse types.
Description
In the M3 software, the operating mode is set using the Sonar Apps menu (found at the top of the presentation).
This API command requires a mode number (PRI Sequence ID). You can find a list of mode numbers in the Database Editor software.
Details
Set Mode API
<Command>
<Operation>Set_Mode</Operation>
<Mode>123</Mode>
</Command>
Related topics
Finding a mode number


Set TVG
When an acoustic pulse is sent through the water, it will gradually lose its energy. The greater the distance between the transducer and the target(s), the greater the loss of energy. TVG (Time Variable Gain) compensates for the loss of acoustic energy due to geometric spreading and absorption.
Description
In the M3 software, the TVG parameters are set using the TVG button located on the tool bar.
Each sonar application has its own TVG profile. If you wish to change the TVG profile for a specific application, issue the Set Mode API command before the Set TVG command. Otherwise, the Set TVG command will configure the default sonar application.
Details
The TVG compensation is expressed as a logarithmic curve. You can choose from a selection of curves. Each curve has a different slope creating a different gain compensation. Four adjustable factors are used to set the gain curve.
Set TVG API
<Command>
<Operation>Set_TVG</Operation>
<TVG_A>20</TVG_A>
<TVG_B>100</TVG_B>
<TVG_C>-16</TVG_C>
<TVG_L>100</TVG_L>

</Command>


Stop Ping
If the Sonar Head is running, the Stop Ping function pauses operation of the head.
Description
When you want to stop operation of the Sonar Head, use the Disconnect API command. The Disconnect function stops communication with the Sonar Head. The Stop Ping command, however, pauses operation of the Sonar Head without disconnecting from it. When you issue this command to pause the Sonar Head, you can use the Start Ping command to resume pinging.
In the M3 software, the Pause function is the equivalent of the Stop Ping command. Click the circular icon in the top-right corner of the sonar view to open the Menu Widget. Then, click Pause.
Details
Stop Ping API
<Command>
<Operation>Stop_Ping</Operation>
</Command>


Start Ping
If the Sonar Head is paused, the Start Ping function resumes operation and starts “pinging”.
Description
When you want to start operation of the Sonar Head, use the Connect API command. The Connect function establishes communication between the M3 software and Sonar Head, then starts “pinging”. Issuing an additional Start Ping command is therefore not necessary. However, if you pause the Sonar Head, then use Start Ping to resume pinging.
Note
Attempting to execute this command when the Sonar Head is not connected will elicit a FAIL response.
In the M3 software, the Resume function is the equivalent of the Start Ping command. Click the circular icon in the top-right corner of the sonar view to open the Menu Widget. Then, click Resume.
Details
Note
You can include the operating mode in this API command, but this is optional. The Set Mode command can be used instead.
Start Ping API
<Command>
<Operation>Start_Ping</Operation>
<Mode>123</Mode> (Optional)
</Command>


Start Record
Record allows you to record echo data.
Description
This function records a sonar data sequence and saves it in a time-stamped digital format. Your recording will be saved under the folder “C:\KML\M3_V0254\Recordings” by default.
In the M3 software, the Record function can be found in the Menu Widget. Click the circular icon in the top-right corner of the sonar view to open the Menu Widget.
Details
Start Record API
<Command>
<Operation>Start_Record</Operation>
</Command>


Stop Record
If you are recording, the Stop Record API command will stop the recording activity.
Description
In the M3 software, the Stop Recording function can be found in the Menu Widget. Click the circular icon in the top-right corner of the sonar view to open the Menu Widget.
Details
Stop Record API
<Command>
<Operation>Stop_Record</Operation>
</Command>


Start Export
The Export function allows you to send echo data to third-party software through the UDP port.
Description
Sonar data is exported using the “.ALL” format, which is a proprietary Kongsberg EM-series datagram format.
In the M3 software, the Export function can be found in the Menu Widget. Click the circular icon in the top-right corner of the sonar view to open the Menu Widget. A flashing red dot with “EXP” next to it will appear when exporting profile data.
Note
You can only export data in a profiling mode (using one of the Profiling sonar applications). You can use the Set Mode API command to enable a profiling mode.
You will still get a FAIL response if you have not set the Remote IP Address, if the Display Mode is not set to “Image and Profile” or “Profile Only”, or if the Exporting Format is not set to “Profile Point (.all)”.
Details
Start Export API
<Command>
<Operation>Start_Export</Operation>
</Command>
Related topics
Streaming ALL data for profiling applications
ALL streaming


Stop Export
If you are exporting data, the Stop Export API command will stop the export.
Description
In the M3 software, the Stop Exporting function can be found in the Menu Widget. Click the circular icon in the top-right corner of the sonar view to open the Menu Widget.
Details
Stop Export API
<Command>
<Operation>Stop_Export</Operation>
</Command>


Frequency
There are transducers with varying frequencies available for the M3 Sonar.
If you have a high-frequency M3 Sonar transducer, the Frequency function allows you to change the frequency. The Frequency function will not work if you are using a 500 kHz transducer.
Each frequency has a different mode number (PRI Sequence ID). When creating a command script, we recommend setting the frequency before setting the mode.
Description
In the M3 software, you can change the frequency using the Display Widget. Click the Display Widget icon. This icon is located in the lower-right corner of the sonar view.
Details
Frequency API
<Command>
<Operation>Set_Frequency</Operation>
<Frequency>1200</Frequency>
</Command>
Tip
You can test the Frequency function by creating a command script, then using the Open Custom Command feature in the M3 Sonar API Testing software.


API responses
For every XML string successfully sent to the server, the host TCP server will issue a response string to be received by the TCP client. You can read these responses to understand the result of the last API command sent to the server.
Description
All API commands received will be acknowledged with a response indicating whether or not the command was successful. The server will reply with a status of OK, FAIL, or BAD_CMD. If a command is a valid command, but it is not possible to get a completion status for that command, then UNKNOWN will be returned. If you are using the API Testing software, then all responses will be saved to a log file.
Tip
The <Message> tag gives you further information about the status.
Details
OK
This response indicates that the command request was successfully completed.
<Response>
<Operation>Connect</Operation>
<Status>OK</Status>
<Message>Connected to 11120091</Message>
<Time>2016-09-13 15:22:21</Time>
</Response>
FAIL
This response indicates that the command was valid, but could not be completed.
<Response>
<Operation>Connect</Operation>
<Status>FAIL</Status>
<Message>Timed out attempting to connect to 11120091</Message>
<Time>2016-09-13 15:22:21</Time>
</Response>
BAD_CMD
This response indicates that the command itself was not valid.
<Response>
<Operation>Unknown</Operation>
<Status>BAD_CMD</Status>
<Message>Invalid Command</Message>
<Time>2016-09-13 15:22:21</Time>
</Response>
UNKNOWN
This response indicates that the command was valid, but it is not possible to determine completion status.
<Response>
<Operation>Start_Export</Operation>
<Status>UNKNOWN</Status>
<Message>Cannot determine status</Message>
<Time>2016-09-13 15:22:21</Time>
</Response>


Data streaming
Topics
IMB streaming
ALL streaming


IMB streaming
You can stream IMB data from the M3 Sonar API once it is connected to the Sonar Head, and the head is running.
Description
IMB streaming differs from ALL streaming in the following way.
• ALL streaming: The M3 Sonar API acts as the client and sends data to an external server.
• IMB streaming: The M3 Sonar API acts as the server which sends data to an external client. This external client must connect to the IMB port of the API.
The default port for 32-bit IMB streaming is 20001, and the default port for 8-bit streaming is 21001. You can change the default 32-bit IMB port of the M3 Sonar API by editing the “UsersInfo.xml” file and finding the <DataExport_IMB_Port> XML tag.
The M3 software automatically creates a port for 8-bit IMB streaming based on the current <DataExport_IMB_Port> value. The port for 8-bit IMB streaming is always the <DataExport_IMB_Port> value plus 1000. For example, if you set the <DataExport_IMB_Port> value to 30001, then the 8-bit IMB port will be 31001.
No API commands are needed for the IMB data to start streaming. As soon as your TCP/IP client connects to one of the IMB ports of the API (either the <DataExport_IMB_Port> value or <DataExport_IMB_Port> + 1000), the IMB data will start streaming back to the client.
Note
The IMB data format is quite large and the data rate could be hundreds of megabits per second, depending on the sonar application (mode) and range selected.
Details
.imb
This format consists of beamformed data.
You can choose between a 32-bit floating point complex or 8-bit integer magnitude format. Select the 8-bit format only if you are interested in imaging pixel data and want a reduced data file size. The 8-bit format takes up a quarter of the 32-bit format's size.
Data body size is determined by the number of beams and samples. Different modes may form a different number of beams. Therefore, data body size may change depending upon the mode.
Tip
For technical details on this format, refer to the document “IMB Beamformed Data Format” (Document number 922-20007002).
Related topics
Changing the IMB port number


ALL streaming
ALL streaming is for profiling applications. To start streaming ALL data, you must use the Start Export API command.
Description
ALL streaming differs from IMB streaming in the following way.
• IMB streaming: The M3 Sonar API acts as the server which sends data to an external client.
• ALL streaming: The M3 Sonar API acts as the client and sends data to an external server. You must enter the IP address of this external server into the <DataExport_Dest_IPAddr> XML tag found in the “UsersInfo.xml” file.
Details
.ALL
This is the proprietary Kongsberg EM series datagram format. The M3 software can output this data format to be compatible with third-party post-processing software.
Related topics
Streaming ALL data for profiling applications
Start Export


API Testing software
Note
You may use the source code of the API Testing software as an example to help you create your own custom application. You can view the source code by navigating to C:\KML\M3_V0254\API_Tester.
Topics
API Testing software dialog box - Testing page
API Testing software dialog box - Configuration page


API Testing software dialog box - Testing page
Use the Testing page to write and execute a Command Script, then view the results in the Test Execution Log.
How to open
Click the Testing tab in the API Testing software.
Description
The Testing page allows you to make sure the M3 Sonar API is working as expected. You can also save any script you create so that you can run the same test at a later date.
To delete a command, select the command in the Command Script pane, then click Delete. Clicking Delete All will remove all commands from the Command Script pane.
After creating your script, click the Execute button to send the API commands to the Commands Port. You can abort script execution by clicking Cancel.
This page also allows you to display a sonar image so that you can verify operation of the Sonar Head and verify that the M3 Sonar API is streaming IMB data.
Details
Connect
The Connect function establishes communication between the M3 software and Sonar Head, then starts “pinging”. Click the Add button to add this command to your script.
Disconnect
The Disconnect function stops operation of the Sonar Head. Click the Add button to add this command to your script.
Get Status
The Get Status function displays information about the Sonar Head and M3 software in the API response text. Click the Add button to add this command to your script.
Set TVG
TVG (Time Variable Gain) compensates for the loss of acoustic energy due to geometric spreading and absorption. Click the Add button to add this command to your script. Four adjustable factors are used to set the gain curve. You can edit these values in the text boxes.
Set Mode
The Set Mode function allows you to set the optimal operating mode for your application. Each mode has its own pre-defined characteristics, such as differing ranges, angular resolutions, and pulse types. This API command requires a mode number (PRI Sequence ID). You can find a list of mode numbers in the Database Editor software. Enter a value into the text box.
Start Ping
If the Sonar Head is paused, the Start Ping function resumes operation and starts “pinging”. Click the Add button to add this command to your script.
Stop Ping
If the Sonar Head is running, the Stop Ping function pauses operation of the head. Click the Add button to add this command to your script.
Record
Record allows you to record echo data. Click the Add Start button to add this command to your script. If you are recording, the Stop Record API command will stop the recording activity. Click the Add Stop button to add this command to your script.
Export
Exporting “.ALL” data is not supported in the M3 Sonar.
Delay
The Delay function is a “control” statement simply used to add a delay between API commands. The Delay function is only used in the API Testing software. However, you can code a delay between API commands into your custom application. Click the Add button to add this command to your script.
Open Custom Command
This feature is useful in the event that new API commands are supported in the M3 Sonar API, but you are still running an old version of the API Testing software. Adding the new command to an XML file will allow you to test it. The “Commands” folder contains XML files of all supported API commands — this folder is a good place to add your custom command. Click the Add button to browse for an XML file that you can add to the Command Script pane.
Save Command Script
Click the Save button to create an XML commands file that you can run later.
Open Command Script
Click the Open button to open an XML commands file. Opening a file will add the commands to the Command Script pane, but will not remove commands already listed in the pane.
Display Sonar Image
Check the Display Sonar Image box, then click the Connect button to open the Sonar Image window.
Related topics
Testing the M3 Sonar API


API Testing software dialog box - Configuration page
Use the Configuration page to set the IP address of the computer running the M3 Sonar API and to configure which ports the API Testing software uses to communicate with the API.
How to open
Click the Configuration tab in the API Testing software.
Description
The Configuration page allows you to change the parameters you need to connect to the M3 Sonar API.
These parameters match the default values defined in the “UsersInfo.xml” file of the M3 Sonar API. If you change the default values in the “UsersInfo.xml” file, then you must change the values here too.
Altered parameters on this page will only be saved if you overwrite the “Default.xml” file or create your own configuration file.
You can also change the location of your log files.
Details
IP Address for M3 Sonar API
If the M3 Sonar API is running on the same computer as the API Testing software, leave the IP Address as 127.0.0.1. 127.0.0.1 is a loopback address (localhost). This address establishes an IP connection to the same computer that you are using. If the M3 Sonar API is running on a different computer, enter that computer’s IP Address.
Note
Do not enter the Sonar Head’s IP Address.
Execution Timeout
During script execution, if the M3 Sonar API doesn’t respond within the timeout defined here, then script execution will end and an error message will appear. Enter the number of seconds before the timeout occurs.
Commands Port #
The Commands Port receives API commands from the API Testing software. Make sure this value matches the port defined in the <API_Commands_Port> XML tag in the “UsersInfo.xml” file of the M3 Sonar API.
IMB Port #
The IMB Port sends data to the API Testing software.
IP/Port# Configuration File
Click the Open button to choose a Configuration File to load. Click the Save button to save the IP Address and Commands Port parameters into a new or existing Configuration File.
Log Folder
Click the Open button to choose a folder for your log files. Click the Default button to reset the log file location to the default folder.


3 Changing the IMB port number
The default port for 32-bit IMB streaming is 20001, and the default port for 8-bit streaming is 21001. You can change the default 32-bit IMB port of the M3 Sonar API by editing the “UsersInfo.xml” file and finding the <DataExport_IMB_Port> XML tag.
Prerequisites
Download and install a free XML file editor, such as Notepad++.
Note
Avoid using the default Notepad editor in Windows, as it may insert hidden characters into XML files that will cause the M3 Sonar API to crash.
Context
The M3 software automatically creates a port for 8-bit IMB streaming based on the current <DataExport_IMB_Port> value. The port for 8-bit IMB streaming is always the <DataExport_IMB_Port> value plus 1000. For example, if you set the <DataExport_IMB_Port> value to 30001, then the 8-bit IMB port will be 31001.
You can stream IMB data from the M3 Sonar API once it is connected to the Sonar Head, and the head is running. As soon as your TCP/IP client connects to one of the IMB ports of the API (either the <DataExport_IMB_Port> value or <DataExport_IMB_Port> + 1000), the IMB data will start streaming back to the client.
Procedure
1 Navigate to C:\KML\M3_V0254\BIN\SETTINGS
2 Right-click on the file “UsersInfo.xml”.
Observe that a context menu opens.
3 Select Edit with Notepad++ to open the file.
Alternatively, open the file in your preferred XML file editor.
4 Find the XML tag <DataExport_IMB_Port>
5 Change the value between the tags to your desired port number.
6 Click File→Save, then close your XML file editor.
Related topics
IMB streaming


2 Finding a mode number
You can use the Database Editor software to find a mode number for use in the Set Mode API command.
Prerequisites
• The Database Editor software is not part of the M3 software application package. You can obtain the Database Editor software from Kongsberg Discovery.
• Make sure that the M3 software is closed or that the M3 Sonar API is disabled.
Tip
If you wish to disable the M3 Sonar API without rebooting your PC, type taskkill /im m3.exe /f at the command prompt.
Procedure
1 Open the Database Editor software by double-clicking the “M3_DB_Editor.exe” file.
2 Open the database.
a Click File→Import DB.
Observe that a Browse For Folder dialog box opens.
b Navigate to C:\KML\M3_V0254\DB
c Click OK.
Observe that a numbered list of modes appears.
3 Click the “+” button to the left of a mode to expand a sub-list (B) showing the mode numbers (PRI Sequence IDs).
Note
The only valid mode numbers are contained in the expanded sub-list (B) of standard applications. The numbers in the main “root” list (A) are not mode numbers and will not work.
Also, any mode numbers listed under test applications will not work. Do not expand any modes in the main list with “(Test Application)” at the end of the name.
4 Take note of the desired mode number so that you can use it in the Set Mode API command.
5 Close the Database Editor software.
Related topics
Set Mode


6 Automatically enabling the M3 Sonar API at bootup
If you want the M3 Sonar API to start automatically when your computer boots up, you can create a simple batch file.
Prerequisites
• Your Sonar Head must be powered on.
• Your computer must be on the same network as the Sonar Head.
• You must have discovered your Sonar Head using the M3 software.
Procedure
1 Create a batch file.
a In the bottom-left corner of your desktop, type “notepad” into the Windows search box, then press Enter.
Observe that a new text document opens.
b Enter the following line into the text document.
start c:\kml\m3_v0254\bin\m3.exe /api /no_dm
Note
Use the /no_dm switch for imaging applications only. Do not use the /no_dm switch for profiling applications.
c Select File→Save.
d Type “M3Start.bat” into the File name field.
e Select All Files from the Save as type drop-down list.
Note
Leave the Encoding setting as ANSI.
f Click Save.
g Close the text document.
2 Create a shortcut to the batch file.
a Right click the M3Start.bat file on your desktop.
b Select Create shortcut.
3 Add the shortcut to your Startup folder.
a In the bottom-left corner of your desktop, type “run” into the Windows search box, then press Enter.
Observe that the Run dialog box opens.
b Type the following into the Open field.
shell:startup
c Click OK.
Observe that the Startup folder opens.
d Drag the M3Start.bat file into your Startup folder.
4 Reboot your computer.
The batch file should run at bootup.
Tip
You can test the M3 Sonar API functionality in the M3 Sonar API Testing software.
Related topics
Enabling the M3 Sonar API


7 Disabling the M3 Sonar API
You can use the Windows command prompt to disable the M3 Sonar API.
Prerequisites
The M3 Sonar API must be enabled.
Procedure
1 In the bottom-left corner of your desktop, type “cmd” into the Windows search box, then press Enter.
Observe that the Command Prompt window opens.
2 Type the following into the command prompt, then press Enter.
taskkill /im m3.exe /f
Observe that a success message appears in the Command Prompt window.
3 Close the Command Prompt window.
Tip
If you need to disable the M3 Sonar API often, create a batch file (such as “M3Stop.bat”) with the line “taskkill /im m3.exe /f”.


5 Running more than one Sonar Head
In order to run more than one Sonar Head, you must configure and enable multiple instances of the M3 Sonar API.
Prerequisites
• You must have installed the M3 software.
• Your computer must be on the same network as the Sonar Heads.
• Download and install a free XML file editor, such as Notepad++.
Note
Avoid using the default Notepad editor in Windows, as it may insert hidden characters into XML files that will cause the M3 Sonar API to crash.
Procedure
1 Navigate to C:\KML
2 Make multiple copies of the “M3_V0254” folder and rename each folder accordingly.
Make one copy for each Sonar Head that you have. For example, “M3_V0254_1”, “M3_V0254_2”, “M3_V0254_3”, etc. Each “M3_V0254” folder represents one instance of the M3 Sonar API.
3 For each instance of the M3 Sonar API, configure each Sonar Head’s IP address and assign unique port numbers.
a Navigate to C:\KML\M3_V0254_1\BIN\SETTINGS (Replace “M3_V0254_1” with the name you have used for this instance).
b Right-click on the file “UsersInfo.xml”.
Observe that a context menu opens.
c Select Edit with Notepad++ to open the file.
Alternatively, open the file in your preferred XML file editor.
d Find the XML tag <IPAddress>
e Enter the IP address of the Sonar Head you wish to use with this M3 Sonar API instance.
Make sure that you don’t use the same IP address used in another instance.
Tip
By entering the IP address into the “UsersInfo.xml” file, you will not have to discover and connect to the Sonar Head by running the M3 software. However, if you do not know each Sonar Head’s IP address, you may run the M3 software, then click Setup→System Configuration→Devices→Sonar Setup→Discover Sonar Heads to view the IP addresses.
f Enter unique port numbers into the following three XML tags.
<API_Commands_Port> (send API commands from your client to this port)
<DataExport_IMB_Port>
<DataExport_DotALL_Port>
Note
Use any free numbers not used in other instances. For example, if M3_V0254_1’s range of ports is 20000, 20001, and 20002, then use 20010, 20011, and 20012 for M3_V0254_2 (and so on). Using the same port numbers for all instances of the M3 Sonar API will cause a conflict.
g Click File→Save, then close your XML file editor.
h Repeat this procedure for each instance of the M3 Sonar API.
4 Run each instance of the M3 Sonar API.
a In the bottom-left corner of your desktop, type “cmd” into the Windows search box, then press Enter.
Observe that the Command Prompt window opens.
b Run the “m3.exe” file for each instance in the command line.
For example, for three instances, you will run the three different “m3.exe” files found in each folder you created:
start c:\kml\m3_v0254_1\bin\m3.exe /api /no_dm
start c:\kml\m3_v0254_2\bin\m3.exe /api /no_dm
start c:\kml\m3_v0254_3\bin\m3.exe /api /no_dm
5 Send your API commands from your client to the API Commands Port you specified for each instance.
Tip
You can use the API Testing software to send commands to different ports. Click the Configuration tab, then enter the port into the Commands Port # field.


2 Installing the M3 software
If your system is provided with a Sonar Processor, the M3 software has already been installed. If you intend to use your own computer, you must install the software yourself. We recommended installing the latest M3 software on your Sonar Processor.
Prerequisites
• You can find the software on the Kongsberg USB drive included with the system, or you can contact your local dealer or distributor to have the latest software version installed.
• If you are installing a new software version, uninstall the previous version of the M3 software before proceeding.
Note
When running the M3 software for the first time, a Windows Firewall dialog box may appear. Allow access for all networks.
Procedure
1 Launch the installer M3_V0254 Setup.exe.
2 Follow the installation wizard’s instructions and select Standard Installation.
Note
Use the Dual-M3 on Same PC option only if you are using two M3 Sonars. Selecting this option will install two separate copies of the software, with each copy having its own settings. You can identify which copy you are using by observing the top header of the software presentation. The header will read either “M3 - Master Head” or “M3 - Slave Head”.
3 Use the default folder location and check Create a desktop icon, then click Next.
4 Click Yes to install the KML USB Converter when prompted and follow the instructions to finish the installation process.
5 Pin the M3 software icon to the Windows Taskbar.
a Right click on the M3 software icon.
b Click Pin to taskbar.
6 Test the M3 software startup.
a Double click the M3 icon on the desktop to run the M3 software.
b Confirm the software finishes launching without any error windows appearing.


1 Setting the Sonar Processor to High Performance
To avoid slowdowns or disruptions while running the sonar, ensure your Sonar Processor is using all of its processing power and does not go to sleep.
Prerequisites
This procedure is made for the Microsoft® 64-bit Windows 10 operating system.
Procedure
1 In the bottom-left corner of your desktop, select the Windows® Start button.
2 On the menu, select Settings.
Observe that the Settings window opens.
3 Select System.
4 In the menu on the left, select Power & sleep.
5 Make sure that the Sonar Processor will never go to sleep when plugged in.
a Click the Additional power settings link on the right side of the window.
Observe that the Power Options dialog box opens.
b In the menu on the left, select Create a power plan.
c Select the High performance radio button.
d Give your new custom plan a name, then click Next.
e Select Never for both Turn off the display and Put the computer to sleep when plugged in.
f Click Create.
Tip
Once you have created a custom plan, you can adjust some more advanced settings. You may, for example, wish to keep any secondary displays on when the laptop lid is closed. Click Change plan settings next to your custom plan. Click the Change advanced power settings link. Observe that the Power Options dialog box opens. Click the “+” to expand the submenus, then select the desired options from the drop-down lists. At the bottom of the dialog box, select Apply to save your settings.


5 Starting operation of the Sonar Head
To start operation of the M3 Sonar sonar, you may need to make sure that the Sonar Head has been discovered.
Prerequisites
• The M3 software must be running.
• The sound speed has been configured in
Setup→System Configuration→Deployment→Master Reference.
Procedure
1 Click Setup→Connect to start the Sonar Head.
Wait for “Sync OK” to appear on the status bar before collecting data. It takes two minutes to synchronize the Sonar Head clock.
Tip
By default, the M3 software uses the computer’s time to set the Sonar Head clock (Host mode). You can change the time synchronization settings by clicking Setup→System Configuration→Sonar Setup→Time Sync Mode.
2 If you see an error in the Output Messages window, make sure that the Sonar Head has been discovered.
a Click Setup→System Configuration→Devices→Sonar Setup.
b Click Discover Sonar Heads to search for the sonar on the network.
c If the Sonar Head is found, select it, then click Use Discovered Head.
A discovered Sonar Head appears in the Online Sonar Heads list. If the Sonar Head does not appear, the Ethernet connection between the Sonar Processor and Sonar Head has not been established.
d Click Close.


3 Defining the IP address on the computer's network adapter
The communication between the Sonar Processor and the Sonar Head is made using a high-speed Ethernet cable. If a Sonar Processor is not configured to connect to the sonar, you must define which IP Address and Subnet mask the Ethernet adapter in the Sonar Processor shall use for this communication.
Prerequisites
This procedure is made for the Microsoft® 64-bit Windows 10 operating system. It is assumed that you are familiar with the Windows® operating systems, computer technology, and interface principles.
Context
As long as you do not change the Sonar Processor to another computer, or replace the serial adapter in your Sonar Processor, you will only need to do this once.
Procedure
1 On the computer, close the M3 software.
2 Open the Network Connections dialog box.
a In the bottom-left corner of your desktop, select the Windows® search function.
b In the search box, type "Network Connections", and open the Network Connections dialog box.
c Right-click the network adapter you are going to use and select Properties on the shortcut menu.
d On the list of connections, select Internet Protocol 4 (TCP/IPv4), and then Properties.
3 Select Use the following IP address, and type the IP address and network mask.
IP Address: 192.168.1.N ("N" can be any number from 1 to 254, except 234, which is the Sonar Head default.)
Subnet mask: 255.255.255.0
You can leave Default Gateway blank.
4 Select OK to save the settings, then close all the dialog boxes.


4 Streaming ALL data for profiling applications
You can configure the external server that will receive an ALL stream by editing a text file. To start streaming ALL data, you must use the Start Export API command.
Prerequisites
Download and install a free XML file editor, such as Notepad++.
Note
Avoid using the default Notepad editor in Windows, as it may insert hidden characters into XML files that will cause the M3 Sonar API to crash.
Context
Data is exported through the UDP port to an external server. You must enter the IP address of this external server into the <DataExport_Dest_IPAddr> XML tag found in the “UsersInfo.xml” file. To start streaming ALL data, you must use the Start Export API command.
Procedure
1 Configure the IP address of the external server that will receive the ALL stream.
Alternatively, if you prefer using a graphical user interface, you can open the M3 software, click Setup→Preferences, then enter the IP address into the Remote IP Address field. Make sure that the Display Mode in the Profiling Settings dialog box is set to Image and Profile or Profile Only. Also, click File→Exporting Format and make sure that Profile Point (.all) is selected.
a Navigate to C:\KML\M3_V0254\BIN\SETTINGS
b Right-click on the file “UsersInfo.xml”.
Observe that a context menu opens.
c Select Edit with Notepad++ to open the file.
Alternatively, open the file in your preferred XML file editor.
d Find the XML tag <DataExport_Dest_IPAddr>
e Enter the IP address of the external server that will receive the ALL stream.
f Make sure to leave these parameters at the following default values.
<ProfileMode>1</ProfileMode>
<ExportingFormat>19</ExportingFormat>
g Click File→Save, then close your XML file editor.
2 Enable the API.
a In the bottom-left corner of your desktop, type “cmd” into the Windows search box, then press Enter.
Observe that the Command Prompt window opens.
b Type the following into the command prompt, then press Enter.
start c:\kml\m3_v0254\bin\m3.exe /api
Note
Do not use the /no_dm switch for profiling applications.
3 Send the Start Export API command to start exporting.
<Command>
<Operation>Start_Export</Operation>
</Command>
4 When you are done, send the Stop Export API command to stop exporting.
<Command>
<Operation>Stop_Export</Operation>
</Command>
Related topics
Start Export
ALL streaming


6 Enabling the M3 Sonar API
You can use the Windows command prompt to enable the M3 Sonar API.
Prerequisites
• Your computer must be on the same network as the Sonar Head.
• You must have discovered your Sonar Head using the M3 software.
• The M3 software should not be running.
Caution
Do not run the M3 software and the M3 Sonar API at the same time. Running both may cause a conflict with unpredictable results.
Context
The following command-prompt switches can be used when enabling the M3 Sonar API.
• /api
This switch runs the M3 Sonar API in the background. When enabled, the graphical user interface for the M3 software will not be visible.
• /no_dm
This switch disables the internal Display Manager for cases where low CPU usage is needed. Use this switch if you don’t need Display Manager functions.
Note
Use the /no_dm switch for imaging applications only. Do not use the /no_dm switch for profiling applications.
Procedure
1 In the bottom-left corner of your desktop, type “cmd” into the Windows search box, then press Enter.
Observe that the Command Prompt window opens.
2 For imaging applications, type the following into the command prompt, then press Enter.
start c:\kml\m3_v0254\bin\m3.exe /api /no_dm
Alternatively, for profiling applications, type the following into the command prompt, then press Enter.
start c:\kml\m3_v0254\bin\m3.exe /api
If you don’t see any error messages, the M3 Sonar API should be enabled.
Tip
You can test the M3 Sonar API functionality in the M3 Sonar API Testing software.
3 Close the Command Prompt window.
Related topics
Automatically enabling the M3 Sonar API at bootup


4 Changing the Windows regional format to English
If your local Windows settings uses commas for decimal points, the Database Editor will not function properly. To handle the database values properly, you will need to change the Windows regional format to English.
Prerequisites
This procedure is made for the Microsoft® 64-bit Windows 10 operating system. It is assumed that you are familiar with the Windows® operating systems, computer technology, and interface principles.
Procedure
1 In the bottom-left corner of your desktop, select the Windows® Start button.
2 On the menu, select Settings.
Observe that the Windows Settings dialog box opens.
3 Select Time & Language.
4 Select Region.
5 Select English (United States) from the Regional format drop-down list.
6 Close the dialog box by selecting [X] in the upper-right corner.


Document information
• Product: Kongsberg M3 Sonar
• Document: Instruction Manual
• Document number: 922-20007052
• Revision: 1.4
• Date of issue: 19 April 2024
Copyright
The information contained in this document remains the sole property of Kongsberg Discovery Canada Ltd.. No part of this document may be copied or reproduced in any form or by any means, and the information contained within it is not to be communicated to a third party, without the prior written consent of Kongsberg Discovery Canada Ltd..
Warning
The equipment to which this manual applies must only be used for the purpose for which it was designed. Improper use or maintenance may cause damage to the equipment and/or injury to personnel. You must be familiar with the contents of the appropriate manuals before attempting to operate or work on the equipment.
Kongsberg Discovery disclaims any responsibility for damage or injury caused by improper installation, use or maintenance of the equipment.
Disclaimer
Kongsberg Discovery Canada Ltd. endeavours to ensure that all information in this document is correct and fairly stated, but does not accept liability for any errors or omissions.
Support information
If you require maintenance or repair, contact your local dealer. You can contact us by phone at +1 604 464 8144, or by email at: support.vancouver@kd.kongsberg.com. If you need information about our other products, visit https://www.kongsberg.com/discovery/. On our website you will also find a list of our dealers and distributors.


1 Testing the M3 Sonar API
You can use the API Testing software to test the M3 Sonar API functionality.
Prerequisites
• Your Sonar Head must be powered on.
• Your computer must be on the same network as the Sonar Head.
• You must have discovered your Sonar Head using the M3 software.
• The M3 Sonar API must be enabled through the command prompt.
Caution
Do not run the M3 software and the M3 Sonar API at the same time. Running both may cause a conflict with unpredictable results.
Procedure
1 Navigate to C:\KML\M3_V0254\API_Tester
2 Open the API Testing software by double-clicking the “M3_API_Tester.exe” file.
3 Make sure that the IP Address is correct.
a Click the Configuration tab.
b If the M3 Sonar API is running on the same computer as the API Testing software, leave the IP Address as 127.0.0.1.
Note
127.0.0.1 is a loopback address (localhost). This address establishes an IP connection to the same computer that you are using. Do not enter the Sonar Head’s IP Address.
If the M3 Sonar API is running on a different computer, enter that computer’s IP Address.
4 Prepare the software for an API test.
a Click the Testing tab.
b Make sure that the Display Sonar Image box is checked.
c Click the Connect button beside the Display Sonar Image checkbox.
Observe that the Sonar Image window opens. The window will be blank when the sonar is not running.
5 Create and execute a Command Script.
a Click the Add button beside Connect.
b Click the Add button beside Get Status.
c Click the Add button beside Delay (secs).
d Click the Add button beside Disconnect.
e Click the Execute button.
6 Make sure that the sonar view updates in the Sonar Image window.
Tip
You can make the image look brighter by dragging the gain slider located under the image.
7 Observe the Test Execution Logs pane.
Make sure that the script executes as expected.
Make sure that you do not see any error messages, such as FAIL, BAD_CMD, or UNKNOWN.
8 Close the API Testing software.
Related topics
API Testing software dialog box - Testing page