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'.

Parameters:

sentence (bytes) – Sentence string.

Returns:

Calculated checksum.

Return type:

int

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

Usage example
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')
Parameters:
  • msg (bytes) – Message to fix.

  • talker (str or bytes) – Talker ID to set if needed

Returns:

Message in correct format

Return type:

bytes

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.

Parameters:
  • data (bytes) – Binary data.

  • out (bytearray) – Output buffer for 6-bit encoded string.

Returns:

6-bit encoded string if out is not provided.

Return type:

bytes or None

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.

Parameters:
  • data (bytes) – 6-bit encoded string.

  • out (bytearray) – Output buffer for binary data.

Returns:

Binary data if out is not provided.

Return type:

bytes or None

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().

Parameters:
  • data (buffer) – Binary data.

  • bit_offset (int) – data offset in bits.

  • bit_len (int) – Amount of bits to read.

Returns:

Unsigned integer.

Return type:

int

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().

Parameters:
  • data (buffer) – Binary data.

  • bit_offset (int) – data offset in bits.

  • bit_len (int) – Amount of bits to read.

Returns:

Signed integer.

Return type:

int

Classes

class nmea0183.NMEA0183(rx, tx, talker=b'YD', check=True, forward=False, rtc=None)

Creates NMEA0183 interface using UART rx and tx 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 with deinit().

If rtc is specified, then system time of the device will be syncronized with NMEA0183 network upon reception of ZDA or GLL sentences.

Initialization example
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.

Parameters:

talker (bytes) – Talker ID to set.

Returns:

Current talker ID if the parameter is not provided.

Return type:

None or bytes

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.

Parameters:

check (bool) – Flag to set.

Returns:

Current flag status if check is not provided.

Return type:

None or bool

forward([forward])

Enables or disables automatic retransmission of received messages. The rxcallback() can filter certain messages from being forwarded by returning False.

Usage example
# Forward all messages except VDO and VDM
n0183.forward(True)
n0183.rxcallback(0, False, b'$--VDO')
n0183.rxcallback(1, False, b'$--VDM')
Parameters:

forward (bool) – Flag to set.

Returns:

Current flag status if forward is not provided.

Return type:

None or bool

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() with index 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’

Message receiving example
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:

tuple(function, bytes, bool)

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 to rxcallback().

Usage example
# 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
Parameters:

callback – Function to call on sentence query.

Returns:

Current callback if callback parameter is not provided.

Return type:

function[NMEA0183, bytes, bytes, bytes] or None

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())).

Parameters:

msg (bytes) – Message to fix and send.

Returns:

Number of bytes written.

Return type:

int