documentation¶
ais module¶
create functions to decode AIS message from NMEA lines.
This library uses libais and is largely inspired by ais.stream module but decode messages on a line by line basis.
Note the stats part has been removed as we believe this should be implemented by the user if needed.
example:
import lpais.ais as ais
decode = ais.decoder()
with open(data) as inputs:
for line in inputs:
line = line.strip()
if line:
data = decode(line)
# data is None if line didn't result in a new message
if data:
# data is a dictionary containing AIS fields
print(data)
use keep_nmea
option to keep NMEA data into output dictionary,
if enabled a ‘nmea’ field will contain the NMEA line(s), which
will be a concatenation of original lines if it’s a multiline msg.
example:
import lpais.ais as ais
decode = ais.decoder(keep_nmea=True)
with open(data) as inputs:
for line in inputs:
line = line.strip()
if line:
data = decode(line)
if data:
print('NMEA': data['nmea'])
See also
decoder
for more details
-
exception
lpais.ais.
AISError
(**kw)¶ base class for custom exceptions.
initialized with
kw
args that are used to format the string representation.the base implementation add
description
field from self.description, the implementation class is then likely to define adescription
class attribute.the base representation (str) will use the following fields from
kw
:- ‘description’ : details above
- ‘line’ : the text line on which the exception occured
-
__init__
(**kw)¶ Initialize self. See help(type(self)) for accurate signature.
-
exception
lpais.ais.
DecodeError
(**kw)¶ Error while decoding AIS.
the representation will use the following fields from
kw
, in addition to the fields used byAISError
:- ‘error_type’ : error type
- ‘error’ : error message
-
exception
lpais.ais.
DifferingTimestampsError
(**kw)¶ Timestamps not all the same.
the representation will use the following fields from
kw
, in addition to the fields used byAISError
:- ‘timestamp’ : value of the timestamp
- ‘parts’ : parts of the multiline message
-
exception
lpais.ais.
InvalidChecksumError
(**kw)¶
-
exception
lpais.ais.
InvalidChecksumInConstructedError
(**kw)¶
-
exception
lpais.ais.
MissingTimestampsError
(**kw)¶ Timestamps missing.
the representation will use the following fields from
kw
, in addition to the fields used byAISError
:- ‘parts’ : parts of the multiline message
-
exception
lpais.ais.
NoStationFoundError
(**kw)¶
-
exception
lpais.ais.
OnlyMessageEndError
(**kw)¶ Do not have the preceeding packets for a multiline message.
the representation will use the following fields from
kw
, in addition to the fields used byAISError
:- ‘bufferSlot’ : information to identify the message
-
exception
lpais.ais.
TooFewFieldsError
(**kw)¶ Too few fields.
the representation will use the following fields from
kw
, in addition to the fields used byAISError
:- ‘fields’ : number of fields
-
lpais.ais.
decoder
(*args, keep_nmea=False, handle_err=<bound method Logger.error of <Logger lpais.ais (WARNING)>>, **kwargs)¶ create a decoder function used to process NMEA lines one by one.
The created function will take a single text line as input arg and return either:
None
if the line didn’t result as a new decoded AIS messagethis will be the case if it’s a part of a multiline message or thie line could not be properly decoded or processed…
a
dict
containing all the AIS message’s fields.
The parameters used to create the decoder function are:
See also
except for
keep_nmea
, all the parameters are forwarded tonormalizer
function.validate_checksum
: (optional) wether or not to control cs.allow_unknown
: (optional) allow no station.window
: (optional) number of seconds to allow the later parts of a multiline message to span.ignore_tagblock_station
: (optional) dont look for station in tagblock_station.treat_ab_equal
: (optional) dont use A or B to identify msgs.pass_invalid_checksums
: (optional) accept invalid cs.allow_missing_timestamps
: (optional) accept missing ts.handle_err
: (optional) called for every exception, default islogger.error
.keep_nmea
: (optional) keep origin NMEA line(s) and add it as ‘nmea’ field in output dictionary, all NMEA lines will be concatenated if multiline message.
-
lpais.ais.
normalizer
(validate_checksum=True, allow_unknown=False, window=2, ignore_tagblock_station=False, treat_ab_equal=False, pass_invalid_checksums=False, allow_missing_timestamps=False, handle_err=<bound method Logger.error of <Logger lpais.ais (WARNING)>>)¶ create a function which assembles single or multiline messages.
The created function will take a single text line as input arg and return either:
None
if the line didn’t result in a new messagethis will be the case if it’s a part of a multiline message or thie line could not be properly processed…
a tuple (
tagblock
,line
,origin
) wheretagblock
is adict
containing tagblock info,line
is the complete AIS message to decode,origin
is the original NMEA line(s) composed of a concatenation of the lines if it’s a multiline message.
See also
decoder
for args description