Module mqtt.protocol

MQTT generic protocol components module

Functions

make_uint8 (val) Create bytes of the uint8 value
make_uint16 (val) Create bytes of the uint16 value
make_uint32 (val) Create bytes of the uint32 value
make_string (str) Create bytes of the UTF-8 string value according to the MQTT spec.
make_var_length (len) Create bytes of the integer value encoded as variable length field For MQTT v3.1.1: 2.2.3 Remaining Length, For MQTT v5.0: 2.1.4 Remaining Length.
make_uint8_0_or_1 (value) Make bytes for 1-byte value with only 0 or 1 value allowed
make_uint16_nonzero (value) Make bytes for 2-byte value with nonzero check
make_var_length_nonzero (value) Make bytes for variable length value with nonzero value check
parse_string (read_func) Read string (or bytes) using given read_func function
parse_uint8 (read_func) Parse uint8 value using given read_func
parse_uint8_0_or_1 (read_func) Parse uint8 value using given read_func with only 0 or 1 value allowed
parse_uint16 (read_func) Parse uint16 value using given read_func
parse_uint16_nonzero (read_func) Parse uint16 non-zero value using given read_func
parse_uint32 (read_func) Parse uint32 value using given read_func
parse_var_length (read_func) Parse variable length field value using given read_func.
parse_var_length_nonzero (read_func) Parse variable length field value using given read_func with non-zero constraint.
make_header (ptype, flags, len) Create bytes of the MQTT fixed packet header For MQTT v3.1.1: 2.2 Fixed header, For MQTT v5.0: 2.1.1 Fixed Header.
check_qos (val) Check if given value is a valid PUBLISH message QoS value
check_packet_id (val) Check if given value is a valid Packet Identifier For MQTT v3.1.1: 2.3.1 Packet Identifier, For MQTT v5.0: 2.2.1 Packet Identifier.
next_packet_id ([curr]) Returns the next Packet Identifier value relative to given current value.
packet_id_required (args) Check if Packet Identifier field are required for given packet
combine (...) Combine several data parts into one
packet_tostring (packet) Render packet to string representation
start_parse_packet (read_func) Start parsing a new packet
parse_packet_connect (read_func[, version]) Parse CONNECT packet with read_func
parse_packet_connect_input (input[, version]) Parse CONNECT packet from already received stream-like packet input table

Tables

packet_type MQTT protocol fixed header packet types.
packet_mt Parsed packet metatable
connack_packet_mt Parsed CONNACK packet metatable

Fields

max_variable_length Maximum integer value (268435455) that can be encoded using variable-length encoding


Functions

make_uint8 (val)
Create bytes of the uint8 value

Parameters:

  • val number - integer value to convert to bytes

Returns:

    string bytes of the value
make_uint16 (val)
Create bytes of the uint16 value

Parameters:

  • val number - integer value to convert to bytes

Returns:

    string bytes of the value
make_uint32 (val)
Create bytes of the uint32 value

Parameters:

  • val number - integer value to convert to bytes

Returns:

    string bytes of the value
make_string (str)
Create bytes of the UTF-8 string value according to the MQTT spec. Basically it's the same string with its length prefixed as uint16 value. For MQTT v3.1.1: 1.5.3 UTF-8 encoded strings, For MQTT v5.0: 1.5.4 UTF-8 Encoded String.

Parameters:

  • str string - string value to convert to bytes

Returns:

    string bytes of the value
make_var_length (len)
Create bytes of the integer value encoded as variable length field For MQTT v3.1.1: 2.2.3 Remaining Length, For MQTT v5.0: 2.1.4 Remaining Length.

Parameters:

  • len number - integer value to be encoded

Returns:

    string bytes of the value
make_uint8_0_or_1 (value)
Make bytes for 1-byte value with only 0 or 1 value allowed

Parameters:

  • value number - integer value to convert to bytes

Returns:

    string bytes of the value
make_uint16_nonzero (value)
Make bytes for 2-byte value with nonzero check

Parameters:

  • value number - integer value to convert to bytes

Returns:

    string bytes of the value
make_var_length_nonzero (value)
Make bytes for variable length value with nonzero value check

Parameters:

  • value number - integer value to convert to bytes

Returns:

    string bytes of the value
parse_string (read_func)
Read string (or bytes) using given read_func function

Parameters:

  • read_func function - function to read some bytes from the network layer

Returns:

  1. string parsed string (or bytes) on success
  2. OR false and error message on failure
parse_uint8 (read_func)
Parse uint8 value using given read_func

Parameters:

  • read_func function - function to read some bytes from the network layer

Returns:

  1. number parser value
  2. OR false and error message on failure
parse_uint8_0_or_1 (read_func)
Parse uint8 value using given read_func with only 0 or 1 value allowed

Parameters:

  • read_func function - function to read some bytes from the network layer

Returns:

  1. number parser value
  2. OR false and error message on failure
parse_uint16 (read_func)
Parse uint16 value using given read_func

Parameters:

  • read_func function - function to read some bytes from the network layer

Returns:

  1. number parser value
  2. OR false and error message on failure
parse_uint16_nonzero (read_func)
Parse uint16 non-zero value using given read_func

Parameters:

  • read_func function - function to read some bytes from the network layer

Returns:

  1. number parser value
  2. OR false and error message on failure
parse_uint32 (read_func)
Parse uint32 value using given read_func

Parameters:

  • read_func function - function to read some bytes from the network layer

Returns:

  1. number parser value
  2. OR false and error message on failure
parse_var_length (read_func)
Parse variable length field value using given read_func. For MQTT v3.1.1: 2.2.3 Remaining Length, For MQTT v5.0: 2.1.4 Remaining Length.

Parameters:

  • read_func function - function to read some bytes from the network layer

Returns:

  1. number parser value
  2. OR false and error message on failure
parse_var_length_nonzero (read_func)
Parse variable length field value using given read_func with non-zero constraint. For MQTT v3.1.1: 2.2.3 Remaining Length, For MQTT v5.0: 2.1.4 Remaining Length.

Parameters:

  • read_func function - function to read some bytes from the network layer

Returns:

  1. number parser value
  2. OR false and error message on failure
make_header (ptype, flags, len)
Create bytes of the MQTT fixed packet header For MQTT v3.1.1: 2.2 Fixed header, For MQTT v5.0: 2.1.1 Fixed Header.

Parameters:

  • ptype number - MQTT packet type
  • flags number - MQTT packet flags
  • len number - MQTT packet length

Returns:

    string bytes of the fixed packet header
check_qos (val)
Check if given value is a valid PUBLISH message QoS value

Parameters:

  • val number - QoS value

Returns:

    boolean true for valid QoS value, otherwise false
check_packet_id (val)
Check if given value is a valid Packet Identifier For MQTT v3.1.1: 2.3.1 Packet Identifier, For MQTT v5.0: 2.2.1 Packet Identifier.

Parameters:

  • val number - Packet ID value

Returns:

    boolean true for valid Packet ID value, otherwise false
next_packet_id ([curr])
Returns the next Packet Identifier value relative to given current value. If current is nil - returns 1 as the first possible Packet ID. For MQTT v3.1.1: 2.3.1 Packet Identifier, For MQTT v5.0: 2.2.1 Packet Identifier.

Parameters:

  • curr number - current Packet ID value (optional)

Returns:

    number next Packet ID value
packet_id_required (args)
Check if Packet Identifier field are required for given packet

Parameters:

  • args table - args for creating packet

Returns:

    boolean true if Packet Identifier are required for the packet
combine (...)
Combine several data parts into one

Parameters:

  • ... combined_packet_mt/string any amount of strings of combined_packet_mt tables to combine into one packet

Returns:

    combined_packet_mt table suitable to append packet parts or to stringify it into raw packet bytes
packet_tostring (packet)
Render packet to string representation

Parameters:

  • packet packet_mt table to convert to string

Returns:

    string human-readable string representation of the packet
start_parse_packet (read_func)
Start parsing a new packet

Parameters:

  • read_func function - function to read data from the network connection

Returns:

  1. number packet_type
  2. number flags
  3. table input - a table with fields "read_func" and "available" representing a stream-like object to read already received packet data in chunks
  4. OR false and error_message on failure
parse_packet_connect (read_func[, version])
Parse CONNECT packet with read_func

Parameters:

  • read_func function - function to read data from the network connection
  • version number - expected protocol version constant or nil to accept both versions (optional)

Returns:

    packet on success or false and error message on failure
parse_packet_connect_input (input[, version])
Parse CONNECT packet from already received stream-like packet input table

Parameters:

  • input table - a table with fields "read_func" and "available" representing a stream-like object
  • version number - expected protocol version constant or nil to accept both versions (optional)

Returns:

    packet on success or false and error message on failure

Tables

packet_type
MQTT protocol fixed header packet types. For MQTT v3.1.1: 2.2.1 MQTT Control Packet type, For MQTT v5.0: 2.1.2 MQTT Control Packet type.

Fields:

  • CONNECT 1
  • CONNACK 2
  • PUBLISH 3
  • PUBACK 4
  • PUBREC 5
  • PUBREL 6
  • PUBCOMP 7
  • SUBSCRIBE 8
  • SUBACK 9
  • UNSUBSCRIBE 10
  • UNSUBACK 11
  • PINGREQ 12
  • PINGRESP 13
  • DISCONNECT 14
  • AUTH 15
  • [1] "CONNECT"
  • [2] "CONNACK"
  • [3] "PUBLISH"
  • [4] "PUBACK"
  • [5] "PUBREC"
  • [6] "PUBREL"
  • [7] "PUBCOMP"
  • [8] "SUBSCRIBE"
  • [9] "SUBACK"
  • [10] "UNSUBSCRIBE"
  • [11] "UNSUBACK"
  • [12] "PINGREQ"
  • [13] "PINGRESP"
  • [14] "DISCONNECT"
  • [15] "AUTH"
packet_mt
Parsed packet metatable

Fields:

  • __tostring packet-to-human-readable-string conversion metamethod using protocol.packet_tostring()
connack_packet_mt
Parsed CONNACK packet metatable

Fields:

  • __tostring packet-to-human-readable-string conversion metamethod using protocol.packet_tostring()
  • reason_string Returns reason string for the CONNACK packet according to its rc field

Fields

max_variable_length
Maximum integer value (268435455) that can be encoded using variable-length encoding
generated by LDoc 1.5.0 Last updated 2025-06-20 19:38:49