`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

nmea0183 – simple NMEA0183 message processing

Functions

Classes

Methods

Callbacks

Message transmission

`nmea0183` – simple NMEA0183 message processing