Page 4
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..
Changing the IMB port number.................... 28 Streaming ALL data for profiling applications..............29 Running more than one Sonar Head ..................30 Automatically enabling the M3 Sonar API at bootup............32 FUNCTIONS AND DIALOG BOXES..........35 API functions ........................36 M3 Sonar API overview....................36 Connect........................
Page 6
M3 Sonar API Stop Ping ........................40 Start Ping ........................41 Start Record ......................... 42 Stop Record ......................... 42 Start Export........................42 Stop Export........................43 Frequency ........................44 API responses........................45 Data streaming ........................47 IMB streaming......................47 ALL streaming ......................48 API Testing software......................
About this manual 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.
M3 Sonar 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.
M3 Sonar API Instruction Manual 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. Sonar Processor...
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.
Page 12
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.
M3 Sonar API Instruction Manual 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.
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.
Defining the IP address on the computer's network adapter, page 17 Changing the Windows regional format to English, page 18 Starting operation of the Sonar Head, page 19 Enabling the M3 Sonar API, page 20 Disabling the M3 Sonar API, page 21 922-20007052/1.4...
Getting started 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 ®...
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.
Getting started 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.
M3 Sonar API Instruction Manual 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.
Getting started 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 →...
• 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.
Observe that a success message appears in the window. Command Prompt Close the window. Command Prompt 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”. 922-20007052/1.4...
Finding a mode number, page 26 Changing the IMB port number, page 28 Streaming ALL data for profiling applications, page 29 Running more than one Sonar Head, page 30 Automatically enabling the M3 Sonar API at bootup, page 32 922-20007052/1.4...
• 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 Navigate to C:\KML\M3_V0254\API_Tester Open the API Testing software by double-clicking the “M3_API_Tester.exe”...
Page 26
M3 Sonar API Instruction Manual If the M3 Sonar API is running on a different computer, enter that computer’s IP Address. Prepare the software for an API test. Click the tab. Testing Make sure that the box is checked. Display Sonar Image...
Page 27
Operating procedures Make sure that the sonar view updates in the window. Sonar Image You can make the image look brighter by dragging the gain slider located under the image. Observe the pane. Test Execution Logs Make sure that the script executes as expected. Make sure that you do not see any error messages, such as , or FAIL...
Database Editor software from Kongsberg Discovery. • Make sure that the M3 software is closed or that the M3 Sonar API is disabled. If you wish to disable the M3 Sonar API without rebooting your PC, type taskkill /im m3.exe /f at the command prompt.
Page 29
Operating procedures 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.
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.
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>...
• 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. 922-20007052/1.4...
Page 33
Alternatively, open the file in your preferred XML file editor. Find the XML tag <IPAddress> 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.
Commands Port # 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.
Page 35
Operating procedures 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. Enter the following line into the text document. start c:\kml\m3_v0254\bin\m3.exe /api /no_dm Note Use the switch for imaging applications only.
Page 36
M3 Sonar API Instruction Manual You can test the M3 Sonar API functionality in the M3 Sonar API Testing software. Related topics Enabling the M3 Sonar API, page 20 922-20007052/1.4...
Functions and dialog boxes Functions and dialog boxes Topics API functions, page 36 API responses, page 45 Data streaming, page 47 API Testing software, page 49 922-20007052/1.4...
Functions and dialog boxes Connect function establishes communication between the M3 software and Sonar Head, Connect then starts “pinging”. Description → In the M3 software, clicking enables Setup Connect function. Connect Details Connect API <Command> <Operation>Connect</Operation> </Command> Disconnect function stops operation of the Sonar Head. Disconnect Description →...
M3 Sonar API Instruction Manual 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 function.
Functions and dialog boxes Related topics Finding a mode number, page 26 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. (Time Variable Gain) compensates for the loss of acoustic energy due to geometric spreading and absorption.
M3 Sonar API Instruction Manual 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.
Functions and dialog boxes Details Stop Ping API <Command> <Operation>Stop_Ping</Operation> </Command> Start Ping If the Sonar Head is paused, the function resumes operation and starts “pinging”. Start Ping Description When you want to start operation of the Sonar Head, use the API command.
Stop Record API <Command> <Operation>Stop_Record</Operation> </Command> Start Export function allows you to send echo data to third-party software through the UDP Export port. Description Sonar data is exported using the “.ALL” format, which is a proprietary Kongsberg EM-series datagram format. 922-20007052/1.4...
Functions and dialog boxes In the M3 software, the function can be found in the . Click the circular Export Menu Widget icon in the top-right corner of the sonar view to open the . A flashing red dot Menu Widget with “EXP”...
Details Frequency API <Command> <Operation>Set_Frequency</Operation> <Frequency>1200</Frequency> </Command> You can test the function by creating a command script, then using the Frequency Open feature in the M3 Sonar API Testing software. Custom Command 922-20007052/1.4...
Functions and dialog boxes 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.
Page 48
M3 Sonar API Instruction Manual 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.
IMB streaming, page 47 ALL streaming, page 48 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.
IMB streaming client. • : The M3 Sonar API acts as the client and sends data to an external server. ALL streaming You must enter the IP address of this external server into the <DataExport_Dest_IPAddr> XML tag found in the “UsersInfo.xml” file.
Functions and dialog boxes 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, page 50 API Testing software dialog box - Configuration page, page 52...
API Testing software. Testing Description page allows you to make sure the M3 Sonar API is working as expected. You Testing can also save any script you create so that you can run the same test at a later date.
Page 53
Functions and dialog boxes Details Connect function establishes communication between the M3 software and Sonar Connect Head, then starts “pinging”. Click the button to add this command to your script. Disconnect function stops operation of the Sonar Head. Click the button to Disconnect add this command to your script.
API Testing software dialog box - Configuration page Use the page to set the IP address of the computer running the M3 Sonar API Configuration and to configure which ports the API Testing software uses to communicate with the API.
Page 55
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.
Page 56
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.
Page 57
Commands Port # API Testing software dialog box API Testing software dialog box....... 53 description.......... 50, 53 comments disabling send us............5 M3 Sonar API ..........21 configuring Disconnect Sonar Processor .......... 15 API Testing software dialog box....... 51 Connect Disconnect function API Testing software dialog box.......
Page 58
........... 17 Defining the IP address on the network adapter ........... 17 disable the M3 Sonar API ......21 enable the M3 Sonar API ......20, 32 find a mode number ........26 office install the operational software ......16 support ............
Page 59
..........42 Defining the IP address on the network details............42 adapter ........... 17 Status function disabling the M3 Sonar API ......21 description ..........37 enabling the M3 Sonar API......20, 32 details............38 finding a mode number........26 Stop Export function installing the operational software.....
Page 60
M3 Sonar API Instruction Manual Windows regional format changing........... 18 922-20007052/1.4...
Need help?
Do you have a question about the M3 Sonar API and is the answer not in the manual?
Questions and answers