iKommunicate Developer's Guide (SDK)
Welcome to the iKommunicate Developer's Guide
This document should provide a developer with all of the information they need to read marine data from our new iKommunicate NMEA to Signal K Gateway. Most of the focus is on the new Signal K open data format, but it also covers reading NMEA0183 data over TCP or UDP sockets.
Traditionally marine electronic systems, onboard pleasure boats and commercial ships, have used NMEA0183 and more recently NMEA2000 data standards to share data. These standards were created and maintained by the National Marine Electronics Association (NMEA) and full details can be found at…
For developers the costs in becoming an NMEA member, purchasing the specifications and getting products certified can be quite high and this has created a barrier to entry that has stifled and restricted wide spread use of marine data in navigation software, apps and cloud solutions. Also these standards, which are “fit for purpose”, well proven and extensively used throughout the marine industry, are not suited to the modern “connected” world of web apps, cloud services and smart phones and tablets.
As a result of these factors, a small group of software developers with a passion for boating decided to create a modern “web ready” open source data format for boats. Called Signal K, from the maritime signal flag (K=Kilo) which means “I wish to Communicate with you”, this open standard has been slowly growing and building momentum as developers realise that for the first time these is an alternative to the closed world of NMEA, that gives them free access to boat data in a simple and easy to implement format.
The Signal K data specification along with details of the APIs and conventions used, can be found on the Signal K website and it is recommended that you study this information in conjunction with the information in this Developer's Guide. For more information on Signal K visit…
Towards the end of 2015, Digital Yacht decided to develop the first Signal K gateway product that would sit between the closed NMEA world and the open Signal K world converting data in an efficient and effective manner. Called iKommunicate and successfully funded by a Kickstarter campaign, over 500 developers and boat owners, ordered a unit. This proved that there was a real interest in an open data format that could become the catalyst for a new generation of creative and interesting marine apps, that now had access to all of the boat’s data.
iKommunicate is a small black box, that connects to an NMEA2000 network and/or a series of NMEA0183 devices and reads all of the data being received. Then in real time, it converts this data in to Signal K and also in to NMEA0183 Ethernet packets (either UDP or TCP). Any device on the same LAN network as iKommunicate can open a network socket to iKommunicate and stream data across the network.
Initially for Version 1 release, iKommunicate just converts data from NMEA to Signal K, but it will be NMEA2000 certified as a full bi-directional gateway and the intention is to define and support Signal K to NMEA data flow in a future release of the Signal K format and iKommunicate firmware.
iKommunicate passes through all data received, including duplicate data from multiple sources. Any consumer (App) or server must be able to cope with duplicate data sources.
| Feature | Details |
| Processor | ARM Cortex M4 |
| Clock Speed | 120MHz |
| SRAM | 128Kb Internal + 1Mb External |
| SD Card | 8Gb Micro SD Card (internal) |
| Flash ROM | 1Mb Internal |
| NMEA0183 Ports | 3 Isolated Inputs + 2 Differential Outputs |
| NMEA2000 Interface | 1 |
| NMEA2000 LEN | 1 |
| Networking | 1 Ethernet (10/100Mb) |
| Protocols | HTTP, WS, TCP, UDP and Telnet |
| Integral Cables | 1 x 0.75m Power/Data Cable and 1 x 0.75mm NMEA2000 Cable (Micro Male) |
| Unit Dimensions (WxHxD) | 135 x 120 x 48mm |
| Weight | 0.5 Kg |
| Voltage | 10V to 30V DC |
| Power Consumption | 80mA @ 12V DC |
| Declaration of Conformity | CE Marked |
| Packaging | Digital Yacht Cardboard box |
| Packing List | iKommunicate Unit with integral cables, User Manual and 1m Network Cable |
iKommunicate is designed to be connected to a normal wired Ethernet network (10 or 100Mbits) via its RJ45 connector and the supplied network cable. By default it will try to automatically obtain a network address via DHCP and self assign itself an IP address if its DHCP request fails. It can also be configured via its web interface to use manual (static IP) network settings.
It supports two network Discovery services; Windows SDDP and mDNS (commonly known as Bonjour). To test this, connect the iKommunicate to the same network your PC is on and if running Windows, simply open Windows Explorer, go to your Network and you will see “iKommunicate” listed as a network device.
If you double click the “iKommunicate” Device it will open your browser and take you straight to the iKommunicate “Landing” Web Page or if you right click on iKommunicate and select “Properties” it will display the right hand image shown above with all of the iKommunicate information.
If you are using LINUX, open a terminal and use the Avahi tool to browse for network devices. The command is avahi-browse –a or if you want to see all of the information avahi-browse –a –r to resolve all of the discovered data.
For iOS, we recommend a free App called “Discover” and for Android the best one is “Bonjour Browser” which is also available for Windows and Mac.
Using Bonjour/mDNS to discover and automatically connect to iKommunicate provides an excellent customer user experience, which we definitely recommend implementing. For developers, Apple have produced some really good reference material on Bonjour device discovery at…
https://developer.apple.com/bonjour/
Once you know the IP address of iKommunicate, you have the option of creating the following data connections;
- Making HTTP REST API calls to the Signal K schema
- Establish a Web Socket to receive Signal K Delta Messages
- Http connection on http://ikommunicate.local (Port 80) for accessing the iKommunicate “landing” web page where you can get links to hosted web apps or login to the Admin Web Interface to configure the various iKommunicate settings.
- Telnet connection to ikommunicate.local on (Port 23) for diagnostic purposes
- NMEA0183 data connection via TCP at ikommunicate.local on (Port 2000)
- NMEA0183 data connection via UDP on (Port 2000)
Assuming that your iKommunicate unit is installed and powered up (refer to Quick Start Guide for installation information) let us start by checking the iKommunicate administrative web interface. Open a browser on any device that is on the same network as iKommunicate and type http://ikommunicate.local in to the address bar.
This should work on must networks and browsers, but if you have a problem type in the IP address of the iKommunicate or use one of the Discovery tools.You should now see the iKommunicate home page….
There are three buttons on the landing page;
- iKompass App that takes you to the internal iKommunicate web app
- Hosted App that takes you to the index.html page in the “hosted” folder on the SD Card
- Admin Page that takes you to the iKommunicate administrative web interface
Once you are logged in you will see the Information tab, which provides some key info about your iKommunicate unit.
The first tab to look at is the Configuration tab where the iKommunicate settings can be found. Start by entering the Name and MMSI number of your vessel which will be used to identify your boat in the Signal K Schema.
If you have multiple iKommunicate units or you wish to give it a different network device name change the “Network Name” from the default of iKommunicate.
By default iKommunicate will automatically try and get an IP address from the DHCP server on the network. If you would prefer iKommunicate to have a static IP address, you can untick the “Use DHCP” box and enter the network IP address, subnet mask and gateway manually.
Finally on this tab, you can turn on/off the transmission of NMEA0183 data over TCP or UDP protocol. If you want to send data to a navigation program or app that needs to receive NMEA0183 over the network, select the relevant protocol (TCP or UDP) by ticking the box. It is possible to have both modes operating at the same time.
Once you have made all of the changes you need, click the “Apply Changes” button at the bottom of the page and you will see a message saying that iKommunicate will reboot after 5 seconds.
NOTE – Network operation is critical as this is the only way to communicate with iKommunicate and to provide additional information to the normal two RJ45 status LEDs, the Green Status LED also illuminates and flashes to show the network status.
When iKommunicate powers up, after a few seconds it tries to join the Ethernet network and during this time the Green Status LED flashes. It usually takes <10 seconds for it to power up and get a network address via DHCP.
'If it does not find a DHCP server on the network, it will Self Assign itself an IP address in the 169.254.xxx.xxx range and this takes approx. 20 seconds, during which time the Status LED will flash.
If you have set iKommunicate to use a fixed IP address, then it immediately has an IP address and no flashing of the Green Status LED occurs.
In the Administrative tab, you can change the Admin password if you want to stop anyone else that might have access to the network from changing iKommunicate’s settings. Also from this tab, if the network is connected to the internet, you can check for an iKommunicate firmware update and if available download and install it.
iKommunicate includes a simple web app called iKompass that opens a web socket, streams the Signal K data that iKommunicate is creating and displays the results in your browser.
This app is provided so that users have something to use straight away and also so that you can always quickly check that data is available.
To run the App, click the “iKompass App” button on the iKommunicate landing (page 7) and you will see a single web page with a large compass display as shown on the next page.
The App uses scalable vector graphics (SVG) to draw the displays and if you resize the browser window, you will see the graphics get smaller and larger.
Once you have got up to speed with reading Signal K data via a web app, you will probably want to start using your app on the boat. iKommunicate is designed to be a simple web server and can host web apps on its internal Micro SD Card.
By default we include the open source Signal K Instrument Panel app and this can be run by clicking on the “Hosted App” button of the iKommunicate landing page.
For more information on Instrument Panel, click on the link below…
https://github.com/SignalK/instrumentpanel
When writing a web app to be hosted on iKommunicate, it is important that all libraries, graphics and other required files are included within the “hosted” folder on the SD Card. All links in your code should be relative, with no hard coded links outside of the “hosted” folder.
Once you have developed your app, rename the main landing page as index.html and copy all files and folders across to the “hosted” folder on the SD card, making sure to first remove any existing content. Insertion and removal of the iKommunicate micro SD Card, should be done whilst iKommunicate is powered off.
Now when you go to the main iKommunicate landing page and click the “Hosted App” button your web app should be displayed and not the default Instrument Panel app.
iKommunicate provides two methods of accessing Signal K data; HTTP REST API and websocket Delta Messages. Both services are on Port 80 the default for http traffic.
REST APIs are simply HTTP commands to retrieve data from web servers. URLs are used to access specific Signal K data within the schema. Imagine the Signal K schema as a tree with branches containing different groups of data. Once you know the IP address of iKommunicate via the discovery services, you can find out what versions of Signal K iKommunicate supports and the URL “endpoints” for accessing the Signal K data by making an http request to http://ip.address/signalk to which iKommunicate will respond with…
{
"endpoints":
{
"v1":
{
"version": "1.0.0",
"signalk-http": "http://192.168.0.33/signalk/v1/api/",
"signalk-ws": "ws://192.168.0.33/signalk/v1/stream"
}
}
}
As you can see from the returned results, iKommunicate supports Version 1.0.0 of the Signal K specification and the root of the Signal K schema can be found on the iKommunicate at...
http://ip.address/signalk/v1/api/
Knowing the root or “endpoint” of where the Signal K data is stored in iKommunicate, allows you construct specific URLs to make further REST API calls to for instance return the latest depth data. Also included in this “endpoints” file is the websocket URL; ws://192.168.0.33/signalk/v1/stream which you will need to open a Web Socket to receive Signal K delta messages.
The Signal K schema supports the storage of data from multiple vessels. Assuming that there is AIS data coming in, you may have the data for many vessels stored in the iKommunicate memory. To make it easy to extract your own vessel’s data, Signal K defined an alias called “self” which can be used in URLs and Commands when you want to refer to data from your own vessel. For example a web app can specifically request data from Self, with the following URL request…
http://ip.address/signalk/v1/api/vessels/self
This will probably return a long list of all the data values for your vessel and if you want to be more specific, you can just ask for the navigation data by…
http://ip.address/signalk/v1/api/vessels/self/navigation
or if you want to be even more specific and just get the value for your boat’s GPS position…
http://ip.address/signalk/v1/api/vessels/self/navigation/position
Which will return something like this…
{
"position":
{
"timestamp": "2015-09-20T18:51:7.000Z",
"latitude": 47.66245651245117,
"longitude": -122.4427719116211,
"altitude": 2.799999952316284,
"source":
{
"label": "self",
"type": 2,
"src": 2490369,
"pgn": 129029
}
}
}
By studying the Signal K spec, you will be able to see the breakdown of each branch and work out what URL you need to build to access any data object in the schema…
http://signalk.org/specification/1.0.4/doc/
In the future, iKommunicate will support the HTTP “Put” command to allow an app to send data to iKommunicate; either to store settings or to pass data back to NMEA devices.
Included in this GitHub repository is "SDK-Depth-REST-Example-V1.html" a simple HTML and Javascript webpage example, that shows how to use the Http REST API to poll the Depth data every second, extract it from the returned JSON Object and display it on a simple Javascript Gauge.
Using this Depth Gauge as an example and by studying the Signal K specification, it is really easy to modify this webpage to display any numerical Signal K data.
The app can be used with iKommunicate by typing in the IP address of your iKommunicate unit when requested or you can type in "demo.signalk.org" and use the demo data on the Signal K website. You will also need the "depthLibrary" folder in whichever folder you run the app from.
For more advanced web apps that want to display lots of live data, iKommunicate supports the real time streaming of converted data via a web socket using the Signal K Delta File format. All websockets are on port 80 (default) and so you do not need to pass any port information when opening a socket.
iKommunicate is constantly receiving NMEA2000 PGNs and NMEA0183 Sentences and as each new updated NMEA message comes in and is converted into a small Delta File. iKommunicate can stream these small Delta Messages to any device that has opened a web socket.
On a typical boat, with a reasonably sized NMEA network, the amount of data coming in to iKommunicate and being converted in to Delta messages is quite large and some apps may not wish to receive all of this data. To filter the Delta messages that a Signal K gateway/server sends out to an app, the app may “subscribe” to receive particular data when it changes. Subscriptions are a very useful tool and more information can be found at…
http://signalk.org/developers/subscription_protocol.html
Subscriptions are only partially supported in Version 1 of iKommunicate and you can either receive all delta updates (including other vessels) or just the delta updates for your vessel "Self". To initiate a websocket, you must call one of the three URLs listed below. Note the third type "None" is not currently supported by iKommunicate and will return a 501 error.
ws://<ip_addr>/signalk/v1/stream?subscribe=self
ws://<ip_addr>/signalk/v1/stream?subscribe=all
ws://<ip_addr>/signalk/v1/stream?subscribe=none
It should be noted that the default subscription is "Self" and so you can just send ws://<ip_addr>/signalk/v1/stream and this will initiate the websocket with just the delta updates for "Self".
You cannot simply open a Web Socket in a browser and see the data coming in, but some browsers do have extensions to display websocket data. If you are using Chrome, install the “Simple WebSocket Client” extension and then you will be able to display the Delta file data that iKommunicate creates.
Once you have the extension installed, you need to enter one of the three iKommunicate’s web socket URLs listed above and click the “Open” button and Chrome will open a websocket with iKommunicate. You should see the delta updates start to stream in and scroll down the page.
Included in this GitHub repository is "SDK-Deltas-WebSocket-Example-V1.html" a simple HTML and Javascript webpage example, that shows how to open a websocket using the subscription URL command, display the Signal K JSON data and close the websocket.
If you open the above HTML file in Chrome with the Developer Tools turned on (Ctrl+Shft+i) you will first be prompted to enter the IP address of iKommunicate and then you should see a page like the one below.
Clicking on the link at the top of the page opens the web socket with iKommunicate and the Signal K Delta File data starts to be received. To close the websocket, just press any key, which also has the effect of pausing the data reception so you can see the last Signal K message received. You can open and close the websocket as many times as you like and the status will be shown in the Developer console.
The app can be used with iKommunicate by typing in the IP address of your iKommunicate unit when requested or you can type in "demo.signalk.org" and use the demo data on the Signal K website.
We have now revisited the original Web App Examples in our SDK and created two new versions that expand on the code and provide additional functionality. To download these new examples click here.
The Web Socket App can now display the Raw Delta Messages or extract the changing values and display them in a list. In addition it can log the Delta messages to a text file, ideal for fault finding data conversion issues or seeing what data is available from your NMEA networks.
The Rest API App now queries the Environment and Navigation Groups to see what data is available and allows you to select a particular data type that you are interested in i.e. Depth Below Keel and then display this as a Digital or Analogue gauge. The code is written in such a way that more groups and data types can be added by the user, making this app an ideal example for people with limited programming experience.
We thought that the sunlight viewable screen, low power and low price of the Kindle makes it an ideal display for your boat, so we decided to create a simple app optimised for the Kindle Experimental Browser that would display Signal K data.
This simple but effective web app, uses RestAPI calls (every second) to get instrument data from iKommunicate or any other Signal K server. It extracts the IP address of the server from the URL of the web server it was called from, so it works best when installed on the iKommunicate SD Card (hosted folder) or on the Node or Java Signal K servers. If it cannot extract the URL it defaults to reading data from the demo.signalk.org server. In this situation the Cog icon at the bottom of the page is grey.
By making this app open source, we hope that other developers will be able to expand and improve it.
Please email support@digitalyacht.co.uk for more information on iKommunicate.