UbxInterpreter (ubx_interpreter v0.1.0) View Source

Constructs or deconstructs messages that conform to U-blox UBX binary protocol. NOTE: This documentation is incomplete. It will be finished as soon as possible.

Link to this section Summary

Functions

Appends the latest data to any leftover data from the previous check_for_new_message operation.

Similar to check_for_new_message, expect if a valid message is found, the process_fn function will be called. The arguments passed to process_fn include the message class, message ID, and the message payload, plus any additional_fn_args.

Empties the stored payload list

Converts a list of payload bytes to a map containing usable values. The message contents are defined according to the byte_types and multipliers arguments.

Create a new UbxInterpreter struct that can parse new data and store the most recently received output.

Link to this section Functions

Link to this function

calculate_ubx_checksum(buffer)

View Source

Specs

calculate_ubx_checksum(list()) :: binary()

See UbxInterpreter.Utils.calculate_ubx_checksum/1.

Link to this function

check_for_new_message(ubx, data)

View Source

Specs

check_for_new_message(struct(), list()) :: tuple()

Appends the latest data to any leftover data from the previous check_for_new_message operation.

Arguments are the %UbxInterpreter{} struct and the newest data from the whichever source this struct is associated (must already by converted from binary to list).

Returns {%UbxInterpreter{}, [list of payload bytes]}. If no valid UBX message was found, the payload list will be empty. This list is the raw payload contents. In order to convert to usable values, the deconstruct_message_to_map or deconstruct_message_to_list function must be called.

NOTE: After a valid message has been received, the clear function must be called if you do not want the payload values to persist. Otherwise this function will continue to return a populated payload list even if a new valid message has not been received.

Example:

{ubx_interpreter, payload_list} = UbxInterpreter.check_for_new_message(ubx_interpreter, new_data_list)
values_list = deconstruct_message_to_list(byte_types_list, multipliers_list, payload_list)
ubx_interpreter = UbxInterpreter.clear(ubx_interpreter)
Link to this function

check_for_new_messages_and_process(ubx, data, process_fn, additional_fn_args \\ [])

View Source

Specs

check_for_new_messages_and_process(struct(), list(), (... -> any()), list()) ::
  struct()

Similar to check_for_new_message, expect if a valid message is found, the process_fn function will be called. The arguments passed to process_fn include the message class, message ID, and the message payload, plus any additional_fn_args.

This makes it easier to parse and process multiple messages contained within the same data stream. For example, you might have a GPS receiver that is outputing two different messages, and you want to send the contents of each message to a different GenServer.

Example:

 ubx_interpreter =
    UbxInterpreter.check_for_new_messages_and_process(
      ubx_interpreter,
      data_list,
      &process_data_fn/3,
      []
    )

Specs

clear(struct()) :: struct()

Empties the stored payload list

Link to this function

construct_message_from_list(msg_class, msg_id, byte_types, values_list)

View Source

Specs

construct_message_from_list(integer(), integer(), list(), list()) :: binary()

See UbxInterpreter.Utils.construct_message_from_list/4.

Link to this function

construct_message_from_map(msg_class, msg_id, byte_types, multipliers, key, values_map)

View Source

Specs

construct_message_from_map(integer(), integer(), list(), list(), list(), map()) ::
  binary()

See UbxInterpreter.Utils.construct_message_from_map/6.

Link to this function

construct_proto_message(msg_class, msg_id, payload)

View Source

Specs

construct_proto_message(integer(), integer(), binary()) :: binary()

See UbxInterpreter.Utils.construct_proto_message/3.

Link to this function

deconstruct_message_to_list(byte_types, multipliers, payload)

View Source

Specs

deconstruct_message_to_list(list(), list(), list()) :: list()

See UbxInterpreter.Utils.deconstruct_message_to_list/3.

Link to this function

deconstruct_message_to_map(byte_types, multipliers, keys, payload)

View Source

Specs

deconstruct_message_to_map(list(), list(), list(), list()) :: map()

Converts a list of payload bytes to a map containing usable values. The message contents are defined according to the byte_types and multipliers arguments.

First the payload is split up into a list of values, separated according to their lenght in bytes.<br>Acceptable byte_types values and their corresponding primitive data type are as follows:

  • 1 (uint8)
  • 2 (uint16)
  • 4 (uint32)
  • 8 (uint64)
  • -1 (int8)
  • -2 (int16)
  • -4 (int32)
  • -8 (int64)
  • 4.0 (float)
  • 8.0 (double)

NOTE: UBX messages do not typically contain float or double values represented in single-precision or double-precision form. Rather they use integer values with known multiplier to convert them to their decimal values. However, there is no reason we can't store them like this, so if you want to make a custom UBX message that uses float or double, go for it!

Once each value has been converted from a list of bytes to an integer, float, or double, it is then multiplied by the corresponding number in the multipliers list.

Finally it is stored in a map using the key specified by the keys list.

Example: -coming soon-

Specs

new() :: struct()

Create a new UbxInterpreter struct that can parse new data and store the most recently received output.