-
Notifications
You must be signed in to change notification settings - Fork 2
4. Serial Protocol
The gateway will be connected to a computer via USB and in order for the gateway to communicate with an application running on that computer, a number of Proprietary NMEA0183 sentences have been defined.
Sentences that only contain ASCII characters start with a $ symbol and sentences that include the binary PGN data start with a ! symbol.
All PGN numbers are in decimal format and to reduce serial data bandwidth, all binary PGN data is encoded in base64.
All sentences sent over USB DO NOT HAVE an NMEA0183 checksum, as the USB interface has its own CRC data integrity checks. In the future a Checksum ON/OFF setting will be implemented to allow ISO versions of the gateway to output a checksum.
For each RX PGN received from the NMEA2000 network, the gateway will generate a mixed ASCII and Base64 (PGN payload) sentence in the following format...
!PDGY,<pgn#>,p,src,dst,timer,<pgn_data> CR LF
Key
<pgn#> = NMEA2000 PGN number between 0 and 999999
p = Priority 0-7 with 0 being highest and 7 lowest
src = Source Address of the device sending the PGN between 0-251
dst = Destination Address of the device receiving the PGN between 0-255 (255 = global)
timer = internal timer of the gateway in milliseconds 0-999999
<pgn_data> = The binary payload of the PGN encoded in Base64
For each TX PGN the application wishes to send on the NMEA2000 network, the app will send a mixed ASCII and Base64 (PGN payload) sentence in the following format...
!PDGY,<pgn#>,dst,<pgn_data> CR LF
Key
<pgn#> = NMEA2000 PGN number between 0 and 999999
dst = Destination Address of the device that will receive the PGN between 0-255
<pgn_data> = The binary payload of the PGN encoded in Base64
If for any reason the requested PGN was not transmitted a NAK would be sent to the app with the reason for the TX PGN request being rejected. Typical examples would be if the TX PGN was not in the TX List or if the application tries to send a PGN at an update rate faster than the rate recommended in the NMEA2000 specification.
Any rejected TX PGNs, will increment the iKonvert's PGN rejection count by one. It is recommended that during app development, developers check the Network Status Message (see section 4.3) and ensure that their app is not creating any rejected PGNs
To provide the application with useful data about the NMEA2000 network, the gateway generates the following ASCII sentence (at 1Hz)....
$PDGY,000000,29,12,7,12345678,12,31 CR LF
^ ^ ^ ^ ^ ^
1 2 3 4 5 6
Key
Field 1 = Bus Load between 0-99%
Field 2 = Frame Errors (not currently supported)
Field 3 = Number of Devices Live on network
Field 4 = Network Uptime in seconds
Field 5 = Gateway's CAN address
Field 6 = Number of Rejected TX PGN Requests
[NOTE - A PGN number 000000 is used to identify this special network status data, which under normal circumstances would never be seen on an NMEA2000 network]{.ul}
The number of devices on the network is useful to monitor for changes in the network status, although all applications would benefit from maintaining their own NMEA2000 Device List. A change in the number of devices can be the trigger for your application to query the devices on the network.
You will need the Gateway's CAN Address so that your application can know which addressed PGNs are being sent to it and ignore addressed PGNs with a different destination address.
"Rejected TX PGN Requests" counter increments by 1 each time the application tries to transmit a PGN at a rate faster than the default/recommended update rate as defined by the NMEA2000 Appendix B. For instance, if the application tries to send compass heading at 12Hz the count will increase by two every second as the default/recommended update rate is 10Hz.
The Network Status Message is output at 1Hz and the gateway always outputs this Status message even when not on the bus. In this "Off Bus" situation the gateway outputs the sentence below, as an "I'm Alive" type message so the application knows the gateway is powered up but not initialised...
$PDGY,000000,,,,,,, CR LF
To reset the gateway to factory defaults, the app will send an ASCII sentence in the following format...
$PDGY,N2NET_RESET CR LF
A successful factory reset clears all settings, configurations and the TX/RX Lists and generates an ACK sentence back to the app.
To set the RX PGN List that the gateway will store and use, the app will send an ASCII sentence in the following format...
$PDGY,RX_LIST, PGN1,PGN2,PGN3,PGN4.......PGNn CR LF
If received and actioned correctly, iKonvert will generate an ACK message back to the app.
To set the TX PGN List that the gateway will store and use, the app will send an ASCII sentence in the following format...
$PDGY,TX_LIST,PGN1,PGN2,PGN3,PGN4.......PGNn CR LF
If received and actioned correctly, iKonvert will generate an ACK message back to the app.
To get the latest TX and RX lists being used by iKonvert, the app will send an ASCII sentence in the following format...
$PDGY,SHOW_LISTS CR LF
The gateway responds by sending a list of the RX and TX PGNs in this format in ascending order...
$PDGY,ShowRXTable,PGN1,PGN2 and $PDGY,ShowTXTable,PGN1,PGN2
To Initialise the gateway (must be done before gateway goes on bus), the app will send an ASCII sentence in the following format...
$PDGY,N2NET_INIT,<mode> CR LF
Initialises the gateway and enables it to go on to the NMEA2000 network. Any setup/configuration of the Gateway, including TX and RX PGN lists must be done before the initialisation sentence is sent.
If the gateway's TX/RX PGN list is blank (default) just the mandatory TX and RX PGNs are enabled but if the TX/RX lists have PGNs in them, the gateway will use these lists when queried by another network device.
The <mode> field is used to tell the gateway to go in to a particular operating mode. Currently only two modes are defined "NORMAL" and "ALL".
To make the gateway go "Off Bus" so that the application can change its settings, the app will send an ASCII sentence in the following format...
$PDGY,N2NET_OFFLINE CR LF
On receiving this command the iKonvert goes "Off Bus" and reboots.
To setup the gateway with any required configuration settings, the app will send an ASCII sentence in the following format...
$PDGY,N2NET_SETUP,instance,address,baud,checksum, tbd,tbd CR LF
Key
Instance = Integer 0-9
Address = Integer 001-255
Baud = Integer 4800-230400
Checksum = A = enabled V = disabled and default = disabled
When there is a lot of NMEA 2000 streaming through, it is sometimes desirable to stop this so you can see the commands being sent and the ACKs or NAKs.
iKonvert has a special "Command" mode where the display of received NMEA 2000 PGNs is stopped and you just see the commands sent and received by the app. To enter command mode, send an ASCII sentence in the following format...
$PDGY,CMD CR LF
And then to exit command mode, send an ASCII sentence in the following format...
$PDGY,EXIT CR LF
In some situations, it is necessary to send particular PGNs at a faster rate that the NMEA 2000 specification recommends, such as when you have multiple instances and each instance needs to transmit the same PGN at the recommended update rate. To allow for this situation you can set the iKonvert's TX Limit restriction to OFF, by sending an ASCII sentence in the following format...
$PDGY,TX_LIMIT,OFF CR LF
And then to turn the TX Limit ON again, send an ASCII sentence in the following format...
$PDGY,TX_LIMIT,ON CR LF
If received and actioned correctly, iKonvert will generate an ACK message back to the app.
The iKonvert gateway supports a number of different NMEA operating modes. These can be configured by the internal DIP switches or by sending a serial command.
This NMEA Mode serial command is only actioned if the DIP switches are in the 0000 (all off) position. To set the iKonvert's NMEA Mode, send an ASCII sentence in the following format...
$PDGY,N2NET_MODE,n CR LF
Where n = 0 to 15 depending on the required mode -- see iKonvert manual for details of the supported modes.
If received and actioned correctly, iKonvert will generate an ACK message back to the app or if a mode was selected that is no currently supported, iKonvert will generate a NAK message.
To make it easier for an application to maintain an NMEA 2000 device list, the iKonvert gateway automatically maintains a device list with the CAN Address and NMEA Name of every device on the network. To get this list from the iKonvert Gateway, the app needs to send an ASCII sentence in the following format...
$PDGY,GET_N2NET_NAME CR LF
If received and actioned correctly, iKonvert will generate a series of sentences (one for each device) in the following format...
$PDGY,N2NET_NAME,ADDR,NAME
The first sentence that is transmitted is the iKonvert's own Address and Name, followed by the rest of the devices in ascending Address order.
The iKonvert gateway normally passes through all data from any device on the network, but in some situations, such as when there are duplicate data sources or a device is outputting wrong data or data not available value it is desirable to "Blacklist" a device.
You can blacklist up to a maximum of 10 different devices and up to 3 different PGNs for each device. You can blacklist specific PGNs or all PGNs from that device, by sending iKonvert an ASCII sentence in the following format...
$PDGY,BLACKLIST,address,PGN1,PGN2,PGN3 CR LF
Where the address = 0 to 251 and the PGN1, PGN2, PGN3, etc, is the PGN number in decimal format of the PGN you do not want iKonvert to pass through. If you want to blacklist all of the PGNs from a device you send the following command...
$PDGY,BLACKLIST,address,1 CR LF
If received and actioned correctly, iKonvert will generate an ACK message back to the app or if the maximum number of Blacklists has been reached or the address is outside the range 0 to 251, iKonvert will generate a NAK message.
If you wish to clear all of the Blacklist rules in the iKonvert memory, send this command...
$PDGY,RESET_BLACKLIST CR LF
If received and actioned correctly, iKonvert will generate an ACK message back to the app.
To tell the application that the last received sentence was successfully actioned, the N2Net gateway will send an ASCII sentence in the following format...
$PDGY,ACK,message CR LF
Where "message" is the command that was successfully actioned. Below is a list of currently generated ACK messages;
$PDGY,ACK,N2NET_RESET
$PDGY,ACK,RX_LIST
$PDGY,ACK,TX_LIST
$PDGY,ACK,N2NET_INIT,ALL
$PDGY,ACK,N2NET_INIT,NORMAL
$PDGY,ACK,PROD_CONFIG_SAVED
$PDGY,ACK,TX_LIMIT,ON (or OFF)
$PDGY,ACK,N2NET_MODE
$PDGY,ACK,BLACKLIST_ITEM_SAVED
$PDGY,ACK,RESET_BLACKLIST
To tell the application that the last received sentence was not actioned, the N2Net gateway will send an ASCII sentence in the following format...
$PDGY,NAK,error_text CR LF
The NAK sentence includes the associated Error Text that the application will display i.e. "Error - PGN not in TX List". The currently generated NAK messages are;
$PDGY,NAK,ALREADY_INITIALISED
$PDGY,NAK,PGN_NOT_IN_TX_LIST
$PDGY,NAK,NOT_INITIALISED_YET
$PDGY,NAK,SERIAL_NUMBER_NOT_PROGRAMMED
$PDGY,NAK,SERIAL_NUMBER_IS_INCORRECT
$PDGY,NAK,TX_RATE_TOO_HIGH
$PDGY,NAK,FRAME_SIZE_ERROR
$PDGY,NAK,PACKET_SIZE_ERROR
$PDGY,NAK,UNKNOWN_PGN
$PDGY,NAK,WRONG_MODE
$PDGY,NAK,BLACKLIST_IS_FULL
$PDGY,NAK,ADDRESS_BETWEEN_0_AND_251
The serial number NAK messages are only generated in response to special commands used during production and should never be seen in normal operation.
iKonvert Developers Guide V1.02