nmea0183
– simple NMEA0183 message processing
Functions
- nmea0183.checksum(sentence)
Calculates the checksum of a NMEA 0183 sentence.
The
sentence
must be part of the message between the start character (‘$’ or ‘!’) and the checksum delimiter b’*’, e.g.b'YDHDM,207.0,M'
.
- nmea0183.fixmsg(msg[, talker=b'YD'])
Formats the provided
msg
.There are a few ways to change the provided message:
Reason
Action
Start symbol is missing
Adds b’$’ at the beginning of the message
Talker ID is missing
Adds provided
talker
Talker ID equal
'--'
Sets talker ID to the value of
talker
Checksum is missing
Calculates and adds the missing checksum
CR or LF characters are missing
Adds missing carrage return or line feed characters
from nmea0183 import * # Every single line returns same string: b'$YDHDM,207.0,M*3A\r\n' fixmsg(b'$YDHDM,207.0,M*3A\r\n') fixmsg(b'$YDHDM,207.0,M*3A\r') fixmsg(b'$YDHDM,207.0,M*3A\n') fixmsg(b'$YDHDM,207.0,M*3A') fixmsg(b'YDHDM,207.0,M*3A') fixmsg(b'YDHDM,207.0,M*') fixmsg(b'YDHDM,207.0,M') fixmsg(b'$--HDM,207.0,M') fixmsg(b'--HDM,207.0,M') fixmsg(b'HDM,207.0,M')
- nmea0183.encode6bit(data[, out])
Converts binary data to 6-bit encoded string that can be sent in VDM and VDO NMEA 0183 messages.
If
out
is provided, it’s length will be extended if necessary.
- nmea0183.decode6bit(data[, out])
Converts 6-bit encoded string back to binary data.
If
out
is provided, it’s length will be extended if necessary.
- nmea0183.bits_uint(data, bit_offset, bit_len)
Parse raw bits into single unsigned integer.
Primarily used to retrieve AIS data from buffer decoded by
decode6bit()
.
- nmea0183.bits_int(data, bit_offset, bit_len)
Parse raw bits into single signed integer. Sign is determined by MSBit of read integer.
Primarily used to retrieve AIS data from the buffer decoded by
decode6bit()
.
Classes
- class nmea0183.NMEA0183(rx, tx, talker=b'YD', check=True, forward=False, rtc=None)
Creates NMEA0183 interface using UART
rx
andtx
objects. After this it will be impossible to receive/transmit data directly from the specified UARTs. To release the locked UARTs, it is necessary to disable the NMEA0183 object withdeinit()
.If
rtc
is specified, then system time of the device will be syncronized with NMEA0183 network upon reception ofZDA
orGLL
sentences.import pyb import nmea0183 uart_rx = pyb.UART('rx', 4800) uart_tx = pyb.UART('tx', 4800) n0183 = nmea0183.NMEA0183(uart_rx, uart_tx)
Methods
- deinit()
Deinitialize NMEA0183 object and release attached UARTs.
- uart_tx([uart_tx])
Returns or sets the UART object used to send messages.
- Returns:
Current UART object if
uart_tx
is not provided.- Return type:
None or pyb.UART
- uart_rx([uart_rx])
Returns or sets the UART object used to receive messages.
- Returns:
Current UART object if
uart_tx
is not provided.- Return type:
None or pyb.UART
- talker([talker])
Returns or sets the default talker ID used in the NMEA0183 object.
- check([check])
Globally enable or disable reception of messages with missing or incorrect checksums. If enabled, such messages will not be filtered on receipt and will be forwarded to callbacks. The check parameter in the callback should be set to False to allow it to process incorrect messages in this callback.
- forward([forward])
Enables or disables automatic retransmission of received messages. The
rxcallback()
can filter certain messages from being forwarded by returning False.# Forward all messages except VDO and VDM n0183.forward(True) n0183.rxcallback(0, False, b'$--VDO') n0183.rxcallback(1, False, b'$--VDM')
Callbacks
- rxcallback(index[, callback, filter=None, check=False])
Register or remove (
callback=None
) the callback on message reception. A message can be processed with more than one callback. The callback with the lowest index has higher priority and if the message matches its filter and check parameters, it will be called first. If it returns None, the message is checked against other callbacks in ascending index order.Boolean return types in callbacks are used by Gateway for automatic message forwarding. Instead the name of the callback function, True or False can be specified in the callback parameter. This is the short equivalent of specifying an empty function that will only return True or False (see
forward()
for example).To return information about installed callback, call
rxcallback()
withindex
as the only parameter. Information is returned as tuple with parameters (callback
,filter
,check
).The filter allows messages to be selected by talker ID, sentence formatter, type or proprietary sentence formatter or description. The ‘-’ (minus) symbol is used as a wildcard to match a single alphabet at a specific position. Types of filters:
Type
Description
Examples
None
Accept all messages
None or b’’
1 character
Sentence type
b’$’ or b’!’
2 character
Talker ID
b’Y-’, b’GP’
3 character
‘Standart’ sentence formatter
b’HD-’, b’VHW’
4 character
Proprietary sentence formatter
b’PVZH’, b’PGZZ’, b’POPB’
5 character
Proprietary sentence description
b’!PVZH’, b’!PGZZ’, b’$POPB’
6 character
Full ‘standart’ sentence description
b’$YDGGA’, b’!GCAIE’, b’!Y-ABC’
def rx_clbk(n0183, line): line = line[1:line.find(b'*')] # Get everything between b'$' and b'*' args = line.split(b',') print(args) # e.g. [b'YDHDM', b'217.5', b'M'] # Receive every message with 'HD' at the beggining of sentence formatteer, e.g. # b'$YDHDG,217.5,,,7.1,E*38\r\n' # b'$YDHDM,217.5,M*3E\r\n' # b'$GPHDT,224.6,T*37\r\n' n0183.rxcallback(0, rx_clbk, b'$--HD-')
- Parameters:
index (int) – Callback index (priority). Range: [0..15].
callback (function[NMEA0183, bytes] or None or False or True) – Function to be called on message reception or None to disable callback or short equivalent of callback function.
filter (bytes) – Sentence filter or None to accept all messages.
check (bool) – Only allow messages with valid checksum.
- Returns:
None or information on current callback info if
callback
is not specified.- Return type:
- reqcallback([callback])
Sentences queries (5.3.5 of the NMEA 0183 Standard) are not widely used and can be confused with normal sentences because they start with the talker ID of the requester, talker ID of the device from which data is requested and ‘Q’ character (5 characters in total). Therefore there is no NMEA 0183 sentence format that ends with a ‘Q’ character.
If the query callback is not defined, all queries are passed to rxcallback and can be matched with the
b'$----Q'
filter. If the query callback is set, all queries are processed in it and not passed torxcallback()
.# Query of MTW sentence from any device to 'YD' device def mtw(n0183, orig, dest, sentence): if dest == b'YD' and sentence == b'MTW': n0183.send('YDMTW,'+ydpg.cputemp()+',C') n0183.reqcallback(mtw) # $GCYDQ,MTW*2A
Message transmission
- send(msg)
Correct the message if necessary and send to NMEA 0183. This method is equivalent to
NMEA0183.uart_tx().write(nmea0183.fixmsg(msg, NMEA0183.talker()))
.