MQTTSN Class

Properties Methods Events Config Settings Errors

A lightweight, fully-featured MQTT-SN client implementation.

Syntax

class ipworksiot.MQTTSN

Remarks

The MQTTSN class provides a lightweight, fully-featured MQTT-SN (MQTT for Sensor Networks) client implementation over UDP.

Connecting

Connecting to a gateway is easy; in the simplest case, set the client_id property and call the connect_to method, passing it the gateway's hostname and port number.

When connecting to an MQTT gateway, the class sends the following information:

The values of the client_id, clean_session, and keep_alive_interval properties.
The values of the will_topic and will_message properties and the WillRetain and WillQOS configuration settings.

Refer to clean_session for more information about MQTT sessions; refer to will_topic, will_message, WillQOS and WillRetain for more information about MQTT Wills.

Basic Connection Example mqttsn1.ClientId = "testClient"; mqttsn1.CleanSession = true; mqttsn1.KeepAliveInterval = 30; mqttsn1.WillTopic = "wills/" + mqttsn1.ClientId; mqttsn1.WillMessage = mqttsn1.ClientId + " was disconnected ungracefully!"; mqttsn1.ConnectTo(host, port);

Topic Subscriptions

The subscribe and unsubscribe methods are used to subscribe to and unsubscribe from topics.

When subscribing, pass the topic name or id, topic id type and QoS level. Topic filters may contain wildcards in order to match multiple topics on the server. If a topic name is specified, the SubscribedTopicId configuration setting will contain the assigned id for the topic.

Subscribe Examples String fullTopicName = "full/topic/name"; mqttsn1.Subscribe(fullTopicName, 0, 2); // subscribe with topic name int assignedTopicId = mqttsn1.Config("SubscribedTopicId"); // map id to topic name used mqttsn1.Subscribe(fullTopicName+"/#", 0, 2) // topic name with wildcard; SubscribedTopicId will be 0 mqttsn1.OnTopicId += (s,e) => { // will fire before messages matching the wildcard are sent to the client int topicId = e.TopicId; String topicName = e.TopicName; // establish mapping between these }; mqttsn1.Subscribe("aa", 2, 2); // subscribe with short topic name; no need for registration

After subscribing to topics, any messages received on that topic will cause the on_message_in event to fire. Refer to on_message_in for more information about processing steps for inbound messages.

When unsubscribing, pass the topic id or exact topic name used to subscribe.

Unsubscribe Examples String fullTopicName = "full/topic/name"; mqtt1.Unsubscribe(fullTopicName, 0); // unsubscribe from topic name mqtt1.Unsubscribe(fullTopicName+"/#", 0); // must use full topic filter if includes wildcard; can't unsubscribe from individual topics included in the filter mqtt1.Unsubscribe("aa", 2); // unsubscribe from short topic

Refer to subscribe and unsubscribe for more information about subscriptions and topic names.

Publishing Messages

To publish messages to topics, use the publish_message and publish_data methods.

publish_message is used to publish a message with a string payload, while publish_data is used to publish a message with a raw data payload. Both also accept the topic id to publish to, the topic id type and a QoS level at which to publish.

Publish Examples // Publish string messages int id = mqttsn1.RegisterTopic("topic/name"); // must register topic names that are not short or pre-defined mqttsn1.PublishMessage(id, 0, 2, "hello"); // publish message with registered topic name mqttsn1.PublishMessage("aa", 2, 2, "hello"); // publish message with short topic name // Publish a raw data message. byte[] picture = ...; mqtt1.PublishData(id, 0, 2, picture);

Refer to publish_data and publish_message for more information about message publishing as well as topic names.

Sleeping

To save battery, clients may enter a sleep state in which their messages will be buffered for them. To manage sleeping, use start_sleep and stop_sleep. To receive all buffered messages then return to sleep, use fetch_messages.

If the client exceeds the sleep duration passed to start_sleep without waking or sending any packets, it will be considered lost and will disconnect.

Sleep Examples mqttsn1.StartSleep(8); // sleep for 8 seconds // ... wait for 5 seconds mqttsn1.FetchMessages(); // MessageIn will fire for each message buffered during that time // ... wait for 5 more seconds (ok because <8 seconds since last packet sent) mqttsn1.StopSleep();

Property List

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.


clean_session	Determines whether a clean session is used once connected.
client_id	A string that uniquely identifies this instance of the class to the server.
connected	Triggers a connection or disconnection.
keep_alive_interval	The maximum period of inactivity the gateway should allow between receiving messages from the client.
local_host	The name of the local host or user-assigned IP interface through which connections are initiated or accepted.
local_port	The UDP port in the local host where UDP binds.
remote_host	The address of the remote host. Domain names are resolved to IP addresses.
remote_port	The UDP port in the remote host.
timeout	A timeout for the class.
will_message	The message that the server should publish in the event of an ungraceful disconnection.
will_topic	The topic that the server should publish the WillMessage to in the event of an ungraceful disconnection.

Method List

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.


config	Sets or retrieves a configuration setting.
connect	Connects to the MQTTSN Gateway.
connect_to	Connects to the remote host.
disconnect	Disconnect from the MQTTSN Gateway.
discover_gateway	Broadcast a SEARCHGW message to network clients and gateways.
do_events	Processes events from the internal message queue.
fetch_messages	Receive currently buffered messages and return to sleep.
ping	Send a PINGREQ message to the gateway to reset the Keep Alive interval and ensure the gateway's liveliness.
publish_data	Publishes a message with a raw data payload.
publish_message	Publishes a message with a string payload.
register_topic	Register a topic name. Returns the topic id mapped to the newly registered topic name.
reset	Reset the class.
send_discover_response	Asynchronously respond to a SEARCHGW message received from a peer.
start_sleep	Enter sleep state for the specified duration.
stop_sleep	Enter active state, ending the sleep period.
subscribe	Subscribes the class to the specified topic.
unsubscribe	Unsubscribes the class from the specified topic.
update_will_message	Update the will message stored in session state data by the server.
update_will_topic	Update the will topic, will QoS and will retain flag stored in session state data by the server.

Event List

The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.


on_connected	Fired after a MQTTSN connection completes (or fails).
on_disconnected	Fired when a MQTTSN connection is closed.
on_discover_request	Fired when the class receives a SEARCHGW packet from another client.
on_error	Information about errors during data delivery.
on_gateway_info	Fired when the class receives a GWINFO or ADVERTISE packet.
on_log	Fires once for each log message.
on_message_in	Fired when an incoming message has been received and/or fully acknowledged.
on_topic_info	Fired when the client receives a REGISTER packet from the gateway assigning a topic id to a topic name.

Config Settings

The following is a list of config settings for the class with short descriptions. Click on the links for further details.


ConnectionTimeout	How long to wait for a connection attempt to succeed.
Duplicate	Whether to set the Duplicate flag when publishing a message.
LogLevel	The level of detail that is logged.
PingTimeout	Length of time to wait for a PINGRESP packet.
Retain	Whether to set the Retain flag when publishing a message.
SubscribedTopicId	Topic id assigned by the gateway when a topic name is used in a SUBSCRIBE message.
SubscribeDUP	Whether to set the Duplicate flag when subscribe to a topic.
WillQOS	The QoS value to use for the Will message.
WillRetain	Whether the server should retain the Will message after publishing it.
BuildInfo	Information about the product's build.
CodePage	The system code page used for Unicode to Multibyte translations.
LicenseInfo	Information about the current license.
MaskSensitive	Whether sensitive data is masked in log messages.
ProcessIdleEvents	Whether the class uses its internal event loop to process events when the main thread is idle.
SelectWaitMillis	The length of time in milliseconds the class will wait when DoEvents is called if there are no events to process.
UseInternalSecurityAPI	Tells the class whether or not to use the system security libraries or an internal implementation.

clean_session Property

Determines whether a clean session is used once connected.

Syntax

def get_clean_session() -> bool: ...
def set_clean_session(value: bool) -> None: ...

clean_session = property(get_clean_session, set_clean_session)

Default Value

TRUE

Remarks

This property determines whether or not the class should instruct the server to use a clean session when it connects. (Note that this property must be set to the desired value before calling connect.)

By default, clean_session is true, so the server will discard any state data previously associated with the current client_id once the class has connected successfully. In addition, the server will not save any state data when the class disconnects.

Setting clean_session to False before connecting will cause the server to re-associate any previously stored state data for the current client_id. The server will also save any state data that exists when the class is disconnected.

The server-side session state consists of:

client subscriptions,
QoS 1 and 2 messages which are buffering or unacknowledged,
QoS 2 messages received from the client but not completely acknowledged, and
the will_message and will_topic if set.

Note that retained messages are not deleted as a result of a session ending, but are not part of the session state.

client_id Property

A string that uniquely identifies this instance of the class to the server.

Syntax

def get_client_id() -> str: ...
def set_client_id(value: str) -> None: ...

client_id = property(get_client_id, set_client_id)

Default Value

Remarks

The client_id string is used by the server to uniquely identify each client that is connected to it.

If client_id is empty when connect is called, the class's behavior depends on value of clean_session. If clean_session is True, the class will automatically generate a unique value for client_id before connecting. If clean_session is False, the class fails with an error.

connected Property

Triggers a connection or disconnection.

Syntax

def get_connected() -> bool: ...
def set_connected(value: bool) -> None: ...

connected = property(get_connected, set_connected)

Default Value

FALSE

Remarks

This property triggers a connection or disconnection. Setting this property to True makes the class send a CONNECT packet to the MQTTSN Gateway identified by the remote_host property. If successful, after the connection is achieved the value of the property changes to True and the on_connected event is fired.

Setting this property to False sends a DISCONNECT packet, closing the connection.

When connecting to an MQTT gateway, the class sends the following information:

The values of the client_id, clean_session, and keep_alive_interval properties.
The values of the will_topic and will_message properties and the WillRetain and WillQOS configuration settings.

Refer to clean_session for more information about MQTT sessions; refer to will_topic, will_message, WillQOS and WillRetain for more information about MQTT Wills.

keep_alive_interval Property

The maximum period of inactivity the gateway should allow between receiving messages from the client.

Syntax

def get_keep_alive_interval() -> int: ...
def set_keep_alive_interval(value: int) -> None: ...

keep_alive_interval = property(get_keep_alive_interval, set_keep_alive_interval)

Default Value

Remarks

The keep_alive_interval, if set to a non-zero value, is the maximum number of seconds that the gateway will allow the connection to be idle without receiving a message from the client. The value of keep_alive_interval is sent to the server when connect is called; it cannot be changed when the class is already connected.

MQTT servers are required to measure periods of inactivity for all clients who specify a non-zero keep_alive_interval, and must consider them lost if they have not communicated within the keep_alive_interval. The gateway will activate the Will feature for lost clients.

To maintain the connection, the server must send a PINGREQ (ping request) packet within the keep_alive_interval seconds after the most recent message sent. For more see the ping method.

Similarly, if the class doesn't receive a PINGRESP (ping response) packet after multiple retransmissions of the PINGREQ packet, it should first try to connect to another gateway before trying to re-connect to the original one.

If keep_alive_interval is set to 0 (default), the server is not required to consider inactivity. Note that, regardless of keep-alive settings, the server is always free to disconnect clients it deems "unresponsive".

local_host Property

The name of the local host or user-assigned IP interface through which connections are initiated or accepted.

Syntax

def get_local_host() -> str: ...
def set_local_host(value: str) -> None: ...

local_host = property(get_local_host, set_local_host)

Default Value

Remarks

The local_host property contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multi-homed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the class initiate connections (or accept in the case of server classs) only through that interface.

If the class is connected, the local_host property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multi-homed hosts (machines with more than one IP interface).

NOTE: local_host is not persistent. You must always set it in code, and never in the property window.

local_port Property

The UDP port in the local host where UDP binds.

Syntax

def get_local_port() -> int: ...
def set_local_port(value: int) -> None: ...

local_port = property(get_local_port, set_local_port)

Default Value

Remarks

The local_port property must be set before UDP is activated (active is set to True). It instructs the class to bind to a specific port (or communication endpoint) in the local machine.

Setting it to 0 (default) enables the TCP/IP stack to choose a port at random. The chosen port will be shown by the local_port property after the connection is established.

local_port cannot be changed once the class is active. Any attempt to set the local_port property when the class is active will generate an error.

The local_port property is useful when trying to connect to services that require a trusted port in the client side.

remote_host Property

The address of the remote host. Domain names are resolved to IP addresses.

Syntax

def get_remote_host() -> str: ...
def set_remote_host(value: str) -> None: ...

remote_host = property(get_remote_host, set_remote_host)

Default Value

Remarks

The remote_host property specifies the IP address (IP number in dotted internet format) or Domain Name of the remote host.

If remote_host is set to 255.255.255.255, the class broadcasts data on the local subnet.

If the remote_host property is set to a Domain Name, a DNS request is initiated and upon successful termination of the request, the remote_host property is set to the corresponding address. If the search is not successful, an error is returned.

If UseConnection is set to True, the remote_host must be set before the class is activated (active is set to True).

remote_port Property

The UDP port in the remote host.

Syntax

def get_remote_port() -> int: ...
def set_remote_port(value: int) -> None: ...

remote_port = property(get_remote_port, set_remote_port)

Default Value

Remarks

The remote_port is the UDP port on the remote_host to send UDP datagrams to.

A valid port number (a value between 1 and 65535) is required.

If UseConnection is set to True, the remote_port must be set before the class is activated (active is set to True).

timeout Property

A timeout for the class.

Syntax

def get_timeout() -> int: ...
def set_timeout(value: int) -> None: ...

timeout = property(get_timeout, set_timeout)

Default Value

Remarks

This property defines the timeout when sending data. A value of 0 means data will be sent asynchronously and a positive value means data is sent synchronously.

The class will use do_events to enter an efficient wait loop during any potential waiting period, making sure that all system events are processed immediately as they arrive. This ensures that the host application does not "freeze" and remains responsive.

If timeout expires, and the operation is not yet complete, the component throws an exception. Please note that by default, all timeouts are inactivity timeouts, i.e. the timeout period is extended by timeout seconds when any amount of data is successfully sent or received. The default value for the timeout property is 60 seconds.

will_message Property

The message that the server should publish in the event of an ungraceful disconnection.

Syntax

def get_will_message() -> str: ...
def set_will_message(value: str) -> None: ...

will_message = property(get_will_message, set_will_message)

Default Value

Remarks

This property may be set before calling connect to specify to the server a message that should be published on will_topic if the connection is closed ungracefully or lost.

The will_message will only be sent to the server when connect is called if will_topic is set. Note that in MQTTSN the clean session concept is extended to will topic and will message. The will_message can be updated with the update_will_message method.

Refer to will_topic for more information about MQTT Will functionality.

will_topic Property

The topic that the server should publish the WillMessage to in the event of an ungraceful disconnection.

Syntax

def get_will_topic() -> str: ...
def set_will_topic(value: str) -> None: ...

will_topic = property(get_will_topic, set_will_topic)

Default Value

Remarks

This property may be set before calling connect to specify the topic name that the server should publish the will_message on if the connection is closed ungracefully or lost.

MQTT Wills

The Will feature of MQTT allows a client to specify to the server a will_message to publish (as well as a will_topic to publish it on) in the event that the server considers the client lost or ungracefully disconnected.

An "ungraceful disconnection" is any disconnection other than one triggered by calling disconnect. If the client enters sleep mode, the server will not publish the Will. However, if the client is lost as a result of exceeding the sleep duration without sending a message, the server will publish the Will.

In addition to the will_topic and will_message properties, the WillQOS setting may be used to specify the Will message's QoS level, and the WillRetain setting to set the Will message's Retain flag. Refer to those settings for more information.

If will_topic is set to empty string (default) when connect is called, the class will not send a Will to the server.

In MQTTSN, the will_topic, will_message, WillQOS and WillRetain may all be updated using the update_will_message and update_will_topic methods.

config Method

Sets or retrieves a configuration setting.

Syntax

def config(configuration_string: str) -> str: ...

Remarks

config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

connect Method

Connects to the MQTTSN Gateway.

Syntax

def connect() -> None: ...

Remarks

This method connects to the MQTTSN Gateway, specified by remote_host and remote_port, by sending a CONNECT packet. Calling this method is equivalent to setting the connected property to True.

When connecting to an MQTT gateway, the class sends the following information:

The values of the client_id, clean_session, and keep_alive_interval properties.
The values of the will_topic and will_message properties and the WillRetain and WillQOS configuration settings.

Refer to clean_session for more information about MQTT sessions; refer to will_topic, will_message, WillQOS and WillRetain for more information about MQTT Wills.

connect_to Method

Connects to the remote host.

Syntax

def connect_to(host: str, port: int) -> None: ...

Remarks

This method connects to the MQTTSN Gateway, specified by Host and Port, by sending a CONNECT packet. Calling this method is equivalent to setting the remote_host property to Host, setting remote_port to Port, and then setting the connected property to True.

When connecting to an MQTT gateway, the class sends the following information:

The values of the client_id, clean_session, and keep_alive_interval properties.
The values of the will_topic and will_message properties and the WillRetain and WillQOS configuration settings.

Refer to clean_session for more information about MQTT sessions; refer to will_topic, will_message, WillQOS and WillRetain for more information about MQTT Wills.

disconnect Method

Disconnect from the MQTTSN Gateway.

Syntax

def disconnect() -> None: ...

Remarks

This method disconnects from the MQTTSN Gateway by sending a DISCONNECT packet. Calling this method is equivalent to setting the connected property to False.

Refer to the connected property for more information about MQTT-specific behavior.

discover_gateway Method

Broadcast a SEARCHGW message to network clients and gateways.

Syntax

def discover_gateway(broadcast_radius: int) -> None: ...

Remarks

Broadcast a SEARCHGW message in order to discover nearby gateways. Network clients and gateways may respond with a GWINFO message containing a gateway id. Such a response will trigger the on_gateway_info event.

This functionality is not yet implemented.

do_events Method

Processes events from the internal message queue.

Syntax

def do_events() -> None: ...

Remarks

When do_events is called, the class processes any available events. If no events are available, it waits for a preset period of time, and then returns.

fetch_messages Method

Receive currently buffered messages and return to sleep.

Syntax

def fetch_messages() -> None: ...

Remarks

Request any messages currently being buffered by the server for the current sleep period and return to sleep after they have been received.

Any available buffered messages will be sent to the client by the MQTTSN Gateway and the sleep interval will be reset.

This method sends a PINGREQ method with the client_id, requesting buffered messages which will be sent if available (see on_message_in). When the server has sent all messages, it will sent a PINGRESP message, causing the client to re-enter sleep mode. Once the PINGRESP is received, the duration the client may sleep restarts.

ping Method

Send a PINGREQ message to the gateway to reset the Keep Alive interval and ensure the gateway's liveliness.

Syntax

def ping() -> None: ...

Remarks

The client must send a PINGREQ message using this method during each keep_alive_interval period. If the client does not send any message to the gateway during this period, it will be considered lost and will disconnect.

The client also uses this message to supervise the liveliness of the gateway to which they are connected. If a client does not receive a PINGRESP from the gateway even after multiple retransmissions of the PINGREQ message, it should first try to connect to another gateway before trying to re-connect to this gateway.

See keep_alive_interval for more information.

For more detailed requirements regarding Keep Alive intervals and reconnection, refer to the MQTTSN specification.

publish_data Method

Publishes a message with a raw data payload.

Syntax

def publish_data(topic_id: str, topic_id_type: int, qos: int, data: bytes) -> None: ...

Remarks

This method publishes an MQTTSN message with a raw data payload to the specified TopicId at a given QOS level.

The Retain configuration setting may be set before calling this method in order to publish a retained message (see Retain for more information).

Note that the class will only allow one publish flow at a time.

Topic Ids

A topic id is a short identifier corresponding to a longer topic name which is used in MQTTSN due to the limited bandwidth and small message payload in wireless sensor networks.

The type of topic id sent with the message must be specified. TopicIdType may have the following values:

0: Registered topic id
1: Pre-defined topic id
2: Short topic name

A registered topic id identifies a topic name registered with the server before the time of the message. To register a topic id for a given topic name with the gateway so that messages may be published to that topic using that topic id, use the register_topic method.

A pre-defined topic id is one whose mapping to a topic name is known in advance by both the client and the gateway - no registration is necessary.

A short topic name has a fixed length of two bytes and is short enough that no registration is necessary. To use one, simply set the correct TopicIdType and set the TopicId to a two-character string.

Topic Names

Topic names are case-sensitive, must be 1-65535 characters long, and may include any characters except wildcard characters (# and +) and the null character. The / character separates levels within a topic name, which is important in the context of subscribing (see subscribe for more information).

Keep in mind that using topic names with leading or trailing / characters will cause topic levels with zero-length names to be created. That is, a topic name like /a/b/ consists of the levels '', 'a', 'b', and ''. Depending on the server, multiple successive /s may also cause zero-length levels to be created, or may be treated as a single /.

Topic names that begin with a $ are "system topics", and servers will typically prevent clients from publishing to them.

QoS Values

QoS values set the service level for delivery of a message. Values range from -1 to 2 and have the following meanings:


QoS Level	Description
-1	Simple publish - No connection, registration or subscription needed.
0	At most once - The published message is sent once, and if it does not arrive it is lost.
1	At least once - Guarantees that the published message arrives, but there may be duplicates.
2	Exactly once - Guarantees that the publish message arrives and that there are no duplicates.

To send a message with QoS -1, simply set remote_host and remote_host and call publish_message with a pre-defined topic id or short topic name. No connection or registration is necessary. The client will not be informed whether the gateway address is correct, whether the gateway is alive, or whether the messages arrive at the gateway.

Publish QoS -1 Example mqttsn1 = new Mqttsn(); mqttsn1.RemoteHost = gatewayAddress; mqttsn1.RemotePort = gatewayPort; mqttsn1.PublishMessage("aa", 2, -1, "hello"); // publish QoS -1 message; no connection or registration

Republishing Messages

For QoS 1 and 2 messages, the client is responsible for retransmitting the message if it is not fully acknowledged within a reasonable wait time. To do so, set the Duplicate flag configuration setting and call the publish method again.

After a reasonable amount of retransmission attempts, the client should abort the procedure and assume the gateway has disconnected. It should then try to connect to another gateway, only returning to the original if it fails.

publish_message Method

Publishes a message with a string payload.

Syntax

def publish_message(topic_id: str, topic_id_type: int, qos: int, message: str) -> None: ...

Remarks

This method publishes an MQTTSN message with a string payload to the specified TopicId at a given QOS level.

The Retain configuration setting may be set before calling this method in order to publish a retained message (see Retain for more information).

Note that the class will only allow one publish flow at a time.

Topic Ids

A topic id is a short identifier corresponding to a longer topic name which is used in MQTTSN due to the limited bandwidth and small message payload in wireless sensor networks.

The type of topic id sent with the message must be specified. TopicIdType may have the following values:

0: Registered topic id
1: Pre-defined topic id
2: Short topic name

A pre-defined topic id is one whose mapping to a topic name is known in advance by both the client and the gateway - no registration is necessary.

Topic Names

Topic names that begin with a $ are "system topics", and servers will typically prevent clients from publishing to them.

QoS Values

QoS values set the service level for delivery of a message. Values range from -1 to 2 and have the following meanings:


QoS Level	Description
-1	Simple publish - No connection, registration or subscription needed.
0	At most once - The published message is sent once, and if it does not arrive it is lost.
1	At least once - Guarantees that the published message arrives, but there may be duplicates.
2	Exactly once - Guarantees that the publish message arrives and that there are no duplicates.

Republishing Messages

register_topic Method

Syntax

def register_topic(topic_name: str) -> int: ...

Remarks

Requests that the gateway establish a new topic id mapping for the TopicName provided. If accepted, the gateway assigns a topic id to the received topic name and returns it. At this point, the client may begin sending messages with this topic id.

Topic Names

Topic names that begin with a $ are "system topics", and servers will typically prevent clients from publishing to them.

reset Method

Reset the class.

Syntax

def reset() -> None: ...

Remarks

This method will reset the class's properties to their default values.

send_discover_response Method

Asynchronously respond to a SEARCHGW message received from a peer.

Syntax

def send_discover_response(gateway_id: int, gateway_address: str) -> None: ...

Remarks

Asynchronously respond to a SEARCHGW message received from a peer. See also on_discover_request.

This functionality is not yet implemented.

start_sleep Method

Enter sleep state for the specified duration.

Syntax

def start_sleep(duration: int) -> None: ...

Remarks

When this method is called, the gateway will buffer all incoming messages for the client until the next time it awakes. To receive all currently buffered messages, call stop_sleep or fetch_messages.

While in the sleep state, the client no longer must abide by the keep_alive_interval, but must awake before the end of the sleep duration. If it does not send the gateway any messages in this interval, it will be considered lost and will disconnect.

If fetch_messages is called, the client will return to sleep after receiving the messages and the sleep timer will restart. If stop_sleep is called, the client will enter the active state.

stop_sleep Method

Enter active state, ending the sleep period.

Syntax

def stop_sleep() -> None: ...

Remarks

Wake up from the sleep state and receive any messages which were buffered by the gateway during the sleep period. This method must be called before the end of the duration specified in the start_sleep method.

Once active, the client is once again subject to keep_alive_interval supervision just like after connection.

subscribe Method

Subscribes the class to the specified topic.

Syntax

def subscribe(topic_id: str, topic_id_type: int, qos: int) -> None: ...

Remarks

This method subscribes the class to the TopicId using the given QoS level.

TopicIdType indicates the category of value specified in TopicId and may have the following values:

0: Topic name - a full topic name as described in register_topic to be registered by the gateway.
1: Pre-defined topic id - id whose mapping to a topic name is known in advance by both the client and the gateway - no registration is necessary.
2: Short topic name - has a fixed length of two bytes and is short enough that no registration is necessary. To use one, simply set the correct TopicIdType and set the TopicId to a two-character string.

If the topic name option is used, the topic id returned with the SUBACK packet will be accessible in the SubscribedTopicId configuration setting. If a topic name with a wildcard character is used, SubscribedTopicId will be 0. When the gateway has a PUBLISH message with a topic name matching the wildcard to be sent to the client, it will follow the registration process described in on_topic_info.

Topic Filters

A topic filter is a string which can be passed to TopicId when TopicIdType is 0 and can match one or more topic names.

A topic filter is a case-sensitive string between 1 and 65535 characters long (per topic filter), and can include any character other than the null character. Certain characters have special meanings:

/ - The topic level separator
# - The multi-level wildcard (zero or more levels)
+ - The single-level wildcard (exactly one level)
Leading $ - Denotes a "system topic"

Note that both types of wildcards may be used in the same topic filter.

Topic Level Separators

The topic level separator, as its name implies, is used to separate a topic name (or in this case, filter) into "levels". This concept of topic names having levels is what allows topic filters to match multiple topics through the use of wildcards. For the examples in the next sections, assume the following topics exist:

home/floor1
home/floor1/livingRoom
home/floor1/livingRoom/temperature
home/floor1/kitchen/temperature
home/floor1/kitchen/fridge/temperature
home/floor2/bedroom1
home/floor2/bedroom1/temperature

Multi-level Wildcards

The multi-level wildcard character is used at the end of a topic filter to make it match an arbitrary number of successive levels. For example, the topic filter home/floor1/# would match the following topics:

home/floor1 (because it can match zero levels)
home/floor1/livingRoom
home/floor1/livingRoom/temperature
home/floor1/kitchen/temperature
home/floor1/kitchen/fridge/temperature

Here are some things to keep in mind when using a multi-level wildcard:

# must always be the last character in the topic filter (e.g., home/floor1/#/livingRoom is not valid)
# must always be preceded by a / (e.g., home/floor1# is not valid)
# by itself is a valid topic filter, and will match all topics except system topics

Single-level Wildcards

The single-level wildcard character is used between two /s in a topic filter to make it any single level. For example, the topic filter home/floor1/+/temperature would match the following topics:

home/floor1/livingRoom/temperature
home/floor1/kitchen/temperature

Any number of single-level wildcards are supported in a topic filter. For example, the topic filter home/+/+/temperature would match the following topics:

home/floor1/livingRoom/temperature
home/floor1/kitchen/temperature
home/floor2/bedroom1/temperature

Here are some things to keep in mind when using single-level wildcards:

+ must always be separated from other levels using /s (e.g., home/floor1+ is invalid, but +/floor1/+ is valid)
+ by itself is a valid topic filter, and will match all topics with exactly one level in their name except system topics
Remember, topic names with a leading / have a zero-length string as their first level. So a topic named /people would be matched by the topic filter +/+, but not by +
+ must match exactly one level. So for example, the topic filter home/floor1/kitchen/+/temperature would match /home/floor1/kitchen/fridge/temperature, but not home/floor1/kitchen/temperature

QoS Values

QoS values set the service level for delivery of a message. For subscriptions, values range from 0 to 2 and have the following meanings:


QoS Level	Description
-1	Simple publish - No connection, registration or subscription needed.
0	At most once - The published message is sent once, and if it does not arrive it is lost.
1	At least once - Guarantees that the published message arrives, but there may be duplicates.
2	Exactly once - Guarantees that the publish message arrives and that there are no duplicates.

A QoS value of -1 is not applicable to subscriptions.

Note that if this message is being resent, the SubscribeDUP configuration setting must be enabled. For more details on retransmission intervals and counts, see the MQTTSN specification.

unsubscribe Method

Unsubscribes the class from the specified topic.

Syntax

def unsubscribe(topic_id: str, topic_id_type: int) -> None: ...

Remarks

This method unsubscribes the class to the TopicId.

TopicIdType indicates the category of value specified in TopicId and may have the following values:

0: Topic name - a full topic name as described in register_topic to be registered by the gateway.
1: Pre-defined topic id - id whose mapping to a topic name is known in advance by both the client and the gateway - no registration is necessary.
2: Short topic name - has a fixed length of two bytes and is short enough that no registration is necessary. To use one, simply set the correct TopicIdType and set the TopicId to a two-character string.

update_will_message Method

Update the will message stored in session state data by the server.

Syntax

def update_will_message() -> None: ...

Remarks

When this message is called, the value of will_message will be used to update the will message stored by the server.

This method may be called when this value is empty, in this case the server value will be cleared.

See update_will_topic for more on updating will settings.

update_will_topic Method

Update the will topic, will QoS and will retain flag stored in session state data by the server.

Syntax

def update_will_topic() -> None: ...

Remarks

When this message is called, the value of will_topic, WillQOS and WillRetain will be used to update the will message stored by the server.

This method may be called when these values are empty, in this case the server values will be cleared.

See update_will_message for more on updating will settings.

on_connected Event

Fired after a MQTTSN connection completes (or fails).

Syntax

class MQTTSNConnectedEventParams(object):
  @property
  def status_code() -> int: ...

  @property
  def description() -> str: ...

# In class MQTTSN:
@property
def on_connected() -> Callable[[MQTTSNConnectedEventParams], None]: ...
@on_connected.setter
def on_connected(event_hook: Callable[[MQTTSNConnectedEventParams], None]) -> None: ...

Remarks

If no will topic or message is set, this event will fire immediately. If a will topic and the will message are set, this event will be fired after the will packet exchange.

If the connection is made normally, StatusCode is 0 and Description is "OK".

Please refer to the Error Codes section for more information.

Refer to the connected property for more information about MQTT-specific behavior.

on_disconnected Event

Fired when a MQTTSN connection is closed.

Syntax

class MQTTSNDisconnectedEventParams(object):
  @property
  def status_code() -> int: ...

  @property
  def description() -> str: ...

# In class MQTTSN:
@property
def on_disconnected() -> Callable[[MQTTSNDisconnectedEventParams], None]: ...
@on_disconnected.setter
def on_disconnected(event_hook: Callable[[MQTTSNDisconnectedEventParams], None]) -> None: ...

Remarks

If the connection is broken normally, StatusCode is 0 and Description is "OK".

Refer to the connected property for more information about MQTT-specific behavior.

on_discover_request Event

Fired when the class receives a SEARCHGW packet from another client.

Syntax

class MQTTSNDiscoverRequestEventParams(object):
  @property
  def radius() -> int: ...

  @property
  def gateway_id() -> int: ...
  @gateway_id.setter
  def gateway_id(value) -> None: ...

  @property
  def gateway_address() -> str: ...
  @gateway_address.setter
  def gateway_address(value) -> None: ...

  @property
  def respond() -> bool: ...
  @respond.setter
  def respond(value) -> None: ...

# In class MQTTSN:
@property
def on_discover_request() -> Callable[[MQTTSNDiscoverRequestEventParams], None]: ...
@on_discover_request.setter
def on_discover_request(event_hook: Callable[[MQTTSNDiscoverRequestEventParams], None]) -> None: ...

Remarks

This event allows the client to process the received gateway info and decide whether or not to respond to the search request.

If Respond is set to True, the class will respond with a GWINFO packet.

This functionality is not yet implemented.

on_error Event

Information about errors during data delivery.

Syntax

class MQTTSNErrorEventParams(object):
  @property
  def error_code() -> int: ...

  @property
  def description() -> str: ...

# In class MQTTSN:
@property
def on_error() -> Callable[[MQTTSNErrorEventParams], None]: ...
@on_error.setter
def on_error(event_hook: Callable[[MQTTSNErrorEventParams], None]) -> None: ...

Remarks

The on_error event is fired in case of exceptional conditions during message processing. Normally the class fails with an error.

The ErrorCode parameter contains an error code, and the Description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

on_gateway_info Event

Fired when the class receives a GWINFO or ADVERTISE packet.

Syntax

class MQTTSNGatewayInfoEventParams(object):
  @property
  def message_type() -> str: ...

  @property
  def gateway_id() -> int: ...

  @property
  def gateway_address() -> str: ...

  @property
  def interval() -> int: ...

# In class MQTTSN:
@property
def on_gateway_info() -> Callable[[MQTTSNGatewayInfoEventParams], None]: ...
@on_gateway_info.setter
def on_gateway_info(event_hook: Callable[[MQTTSNGatewayInfoEventParams], None]) -> None: ...

Remarks

This event allows packets containing gateway information to be processed. These packets could be received from regular gateway advertisements or gateway info requests from this or other clients. This gateway information is used to manage the client's list of active gateways.

The value of MessageType could be GWINFO or ADVERTISE.

GatewayAddress will be in format host:port.

If the gateway address field is not present in the received GWINFO packet, GatewayAddress will use the packet source IP address.

This functionality is not yet implemented.

on_log Event

Fires once for each log message.

Syntax

class MQTTSNLogEventParams(object):
  @property
  def log_level() -> int: ...

  @property
  def message() -> str: ...

  @property
  def log_type() -> str: ...

# In class MQTTSN:
@property
def on_log() -> Callable[[MQTTSNLogEventParams], None]: ...
@on_log.setter
def on_log(event_hook: Callable[[MQTTSNLogEventParams], None]) -> None: ...

Remarks

This event fires once for each log message generated by the class. The verbosity is controlled by the LogLevel setting.

LogLevel indicates the level of the Message. Possible values are:


0 (None)	No events are logged.
1 (Info - default)	Informational events are logged.
2 (Verbose)	Detailed data is logged.
3 (Debug)	Debug data is logged.

LogType identifies the type of log entry. Possible values are:

Info: General information about the class.
Packet: Packet content logging.
Reconnect: Reconnection status messages.
Session: Session status messages.

on_message_in Event

Fired when an incoming message has been received and/or fully acknowledged.

Syntax

class MQTTSNMessageInEventParams(object):
  @property
  def msg_id() -> int: ...

  @property
  def topic_id() -> str: ...

  @property
  def topic_id_type() -> int: ...

  @property
  def qos() -> int: ...

  @property
  def message() -> bytes: ...

  @property
  def retained() -> bool: ...

  @property
  def duplicate() -> bool: ...

  @property
  def return_code() -> int: ...
  @return_code.setter
  def return_code(value) -> None: ...

# In class MQTTSN:
@property
def on_message_in() -> Callable[[MQTTSNMessageInEventParams], None]: ...
@on_message_in.setter
def on_message_in(event_hook: Callable[[MQTTSNMessageInEventParams], None]) -> None: ...

Remarks

Fired on reception of a PUBLISH packet for QoS 0 and 1 messages, and reception of a PUBREL packet for QoS 2 messages.

MsgId: a unique (among currently unacknowledged incoming messages) identifier attached to messages of QoS 1 and 2. Otherwise value will be 0.
TopicId: topic id of type TopicIdType.
TopicIdType: 0 = registered topic id, 1 = pre-defined topic id, 2 = short topic name.
QOS: The message's QoS level.
Message: The message data.
Retained: Whether or not this message was received as a result of subscribing to a topic.
Duplicate: Whether or not the server has indicated that this message is a duplicate of another message sent previously.
ReturnCode: QoS 1 messages can be accepted or rejected by setting the ReturnCode to a value listed below.
- 0: accepted
- 1: rejected - congestion
- 2: rejected - invalid topic id
- 3: rejected - not supported

Inbound Message Processing

Incoming messages with a QoS of 1 follow these steps:

The on_topic_info event is fired (if the gateway sends a REGISTER packet because it needs to inform the client name and assigned topic id it will use in a PUBLISH message).
The class sends a REGACK (register acknowledgment) packet in response (if a REGISTER packet was received).
The on_message_in event is fired.
The class sends a PUBACK (publish acknowledgment) packet in response (with the return code from the on_message_in event if one is set).

Incoming messages with a QoS of 2 follow these steps:

The on_topic_info event is fired (if the gateway sends a REGISTER packet because it needs to inform the client name and assigned topic id it will use in a PUBLISH message).
The class sends a REGACK (register acknowledgment) packet in response (if a REGISTER packet was received).
The class sends a PUBREC (publish received) packet in response.
The class waits to receive a PUBREL (publish release) packet.
The class sends a PUBCOMP (publish complete) packet in response.
The on_message_in event is fired.

on_topic_info Event

Fired when the client receives a REGISTER packet from the gateway assigning a topic id to a topic name.

Syntax

class MQTTSNTopicInfoEventParams(object):
  @property
  def topic_id() -> int: ...

  @property
  def topic_name() -> str: ...

  @property
  def return_code() -> int: ...
  @return_code.setter
  def return_code(value) -> None: ...

# In class MQTTSN:
@property
def on_topic_info() -> Callable[[MQTTSNTopicInfoEventParams], None]: ...
@on_topic_info.setter
def on_topic_info(event_hook: Callable[[MQTTSNTopicInfoEventParams], None]) -> None: ...

Remarks

A gateway sends a REGISTER packet to a client if it wants to inform that client about the topic name and the assigned topic id that it will use later on when sending PUBLISH messages of the corresponding topic name. The client must establish a new topic id mapping to the topic name indicated.

This happens for example when the client connects without starting a clean session or the client has subscribed to topic names that contain wildcard characters.

When a REGISTER packet is received, the class will respond with a REGACK packet. To set the value of the return code contained in the packet, set it to one of the below values.

0: accepted
1: rejected - congestion
2: rejected - invalid topic id
3: rejected - not supported

When a client subscribes to a topic with wildcard characters, the specific topic names it will receive messages on have not yet been registered to topic ids, so the first step in receiving such messages is the REGISTER packet. It can then receive incoming messages with that id. See on_message_in for more.

MQTTSN Config Settings

The class accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the config method.

MQTTSN Config Settings

ConnectionTimeout: How long to wait for a connection attempt to succeed.

This setting controls how long the class will wait, in seconds, for connection attempt to succeed before timing out. The default is 60 seconds.

Duplicate: Whether to set the Duplicate flag when publishing a message.

When enabled, the component will set the Duplicate flag when a message is published using publish_data or publish_message. See those methods for details on retransmission.

LogLevel: The level of detail that is logged.

This setting controls the level of detail that is logged through the on_log event. Possible values are:


0 (None)	No events are logged.
1 (Info - default)	Informational events are logged.
2 (Verbose)	Detailed data is logged.
3 (Debug)	Debug data is logged.

PingTimeout: Length of time to wait for a PINGRESP packet.

This setting controls how long the class will wait, in seconds, for a response to a ping message before timing out. The default is 5 seconds.

Retain: Whether to set the Retain flag when publishing a message.

When enabled, the class will set the Retain flag when a message is published using publish_data or publish_message. By default, this is disabled.

Publishing a non-empty message with the Retain flag set and a non-zero QoS will cause the server to store it (replacing any previously retained message in the process) so that it can be delivered to any clients which subscribe to the topic in the future. (If the QoS is 0, the server can store the message, but it is not required to do so indefinitely, if at all.)

If the class publishes an empty message with the Retain flag set, then (regardless of its QoS) the server will remove any previously retained message for the topic.

Note that messages with the Retain flag set are still processed by the server and delivered as usual to clients currently subscribed to the topic, regardless of whether they are empty or not. Also note that retained messages are not part of a session's state, they are retained until they are either removed or replaced by another retained message, regardless of whether or not the client connected with clean_session set to True.

SubscribedTopicId: Topic id assigned by the gateway when a topic name is used in a SUBSCRIBE message.

When the client uses a TopicIdType of 0 (topic name), this name must be registered to a topic id. In this scenario, the topic id assigned will be included in the SUBACK message and will be set here when it is received.

See subscribe for more details.

SubscribeDUP: Whether to set the Duplicate flag when subscribe to a topic.

When enabled, the component will set the Duplicate flag when subscribe is called. See that method for details on retransmission.

WillQOS: The QoS value to use for the Will message.

If will_topic is set to a non-empty string when connect is called, this is the QoS value that will be used for the Will message; possible values are 0 (default), 1, and 2. (Note that this setting is ignored if will_topic is empty.)

Refer to will_topic for more information.

WillRetain: Whether the server should retain the Will message after publishing it.

If will_topic is set to a non-empty string when connect is called, this determines whether or not the server will treat the Will message as retained. By default, this is disabled. (Note that this setting is ignored if will_topic is empty.)

See Retain for general information about how retained messages are handled by the server.

Refer to will_topic for more information.

Base Config Settings

BuildInfo: Information about the product's build.

When queried, this setting will return a string containing information about the product's build.

CodePage: The system code page used for Unicode to Multibyte translations.

The default code page is Unicode UTF-8 (65001).

The following is a list of valid code page identifiers:


Identifier	Name
037	IBM EBCDIC - U.S./Canada
437	OEM - United States
500	IBM EBCDIC - International
708	Arabic - ASMO 708
709	Arabic - ASMO 449+, BCON V4
710	Arabic - Transparent Arabic
720	Arabic - Transparent ASMO
737	OEM - Greek (formerly 437G)
775	OEM - Baltic
850	OEM - Multilingual Latin I
852	OEM - Latin II
855	OEM - Cyrillic (primarily Russian)
857	OEM - Turkish
858	OEM - Multilingual Latin I + Euro symbol
860	OEM - Portuguese
861	OEM - Icelandic
862	OEM - Hebrew
863	OEM - Canadian-French
864	OEM - Arabic
865	OEM - Nordic
866	OEM - Russian
869	OEM - Modern Greek
870	IBM EBCDIC - Multilingual/ROECE (Latin-2)
874	ANSI/OEM - Thai (same as 28605, ISO 8859-15)
875	IBM EBCDIC - Modern Greek
932	ANSI/OEM - Japanese, Shift-JIS
936	ANSI/OEM - Simplified Chinese (PRC, Singapore)
949	ANSI/OEM - Korean (Unified Hangul Code)
950	ANSI/OEM - Traditional Chinese (Taiwan; Hong Kong SAR, PRC)
1026	IBM EBCDIC - Turkish (Latin-5)
1047	IBM EBCDIC - Latin 1/Open System
1140	IBM EBCDIC - U.S./Canada (037 + Euro symbol)
1141	IBM EBCDIC - Germany (20273 + Euro symbol)
1142	IBM EBCDIC - Denmark/Norway (20277 + Euro symbol)
1143	IBM EBCDIC - Finland/Sweden (20278 + Euro symbol)
1144	IBM EBCDIC - Italy (20280 + Euro symbol)
1145	IBM EBCDIC - Latin America/Spain (20284 + Euro symbol)
1146	IBM EBCDIC - United Kingdom (20285 + Euro symbol)
1147	IBM EBCDIC - France (20297 + Euro symbol)
1148	IBM EBCDIC - International (500 + Euro symbol)
1149	IBM EBCDIC - Icelandic (20871 + Euro symbol)
1200	Unicode UCS-2 Little-Endian (BMP of ISO 10646)
1201	Unicode UCS-2 Big-Endian
1250	ANSI - Central European
1251	ANSI - Cyrillic
1252	ANSI - Latin I
1253	ANSI - Greek
1254	ANSI - Turkish
1255	ANSI - Hebrew
1256	ANSI - Arabic
1257	ANSI - Baltic
1258	ANSI/OEM - Vietnamese
1361	Korean (Johab)
10000	MAC - Roman
10001	MAC - Japanese
10002	MAC - Traditional Chinese (Big5)
10003	MAC - Korean
10004	MAC - Arabic
10005	MAC - Hebrew
10006	MAC - Greek I
10007	MAC - Cyrillic
10008	MAC - Simplified Chinese (GB 2312)
10010	MAC - Romania
10017	MAC - Ukraine
10021	MAC - Thai
10029	MAC - Latin II
10079	MAC - Icelandic
10081	MAC - Turkish
10082	MAC - Croatia
12000	Unicode UCS-4 Little-Endian
12001	Unicode UCS-4 Big-Endian
20000	CNS - Taiwan
20001	TCA - Taiwan
20002	Eten - Taiwan
20003	IBM5550 - Taiwan
20004	TeleText - Taiwan
20005	Wang - Taiwan
20105	IA5 IRV International Alphabet No. 5 (7-bit)
20106	IA5 German (7-bit)
20107	IA5 Swedish (7-bit)
20108	IA5 Norwegian (7-bit)
20127	US-ASCII (7-bit)
20261	T.61
20269	ISO 6937 Non-Spacing Accent
20273	IBM EBCDIC - Germany
20277	IBM EBCDIC - Denmark/Norway
20278	IBM EBCDIC - Finland/Sweden
20280	IBM EBCDIC - Italy
20284	IBM EBCDIC - Latin America/Spain
20285	IBM EBCDIC - United Kingdom
20290	IBM EBCDIC - Japanese Katakana Extended
20297	IBM EBCDIC - France
20420	IBM EBCDIC - Arabic
20423	IBM EBCDIC - Greek
20424	IBM EBCDIC - Hebrew
20833	IBM EBCDIC - Korean Extended
20838	IBM EBCDIC - Thai
20866	Russian - KOI8-R
20871	IBM EBCDIC - Icelandic
20880	IBM EBCDIC - Cyrillic (Russian)
20905	IBM EBCDIC - Turkish
20924	IBM EBCDIC - Latin-1/Open System (1047 + Euro symbol)
20932	JIS X 0208-1990 & 0121-1990
20936	Simplified Chinese (GB2312)
21025	IBM EBCDIC - Cyrillic (Serbian, Bulgarian)
21027	Extended Alpha Lowercase
21866	Ukrainian (KOI8-U)
28591	ISO 8859-1 Latin I
28592	ISO 8859-2 Central Europe
28593	ISO 8859-3 Latin 3
28594	ISO 8859-4 Baltic
28595	ISO 8859-5 Cyrillic
28596	ISO 8859-6 Arabic
28597	ISO 8859-7 Greek
28598	ISO 8859-8 Hebrew
28599	ISO 8859-9 Latin 5
28605	ISO 8859-15 Latin 9
29001	Europa 3
38598	ISO 8859-8 Hebrew
50220	ISO 2022 Japanese with no halfwidth Katakana
50221	ISO 2022 Japanese with halfwidth Katakana
50222	ISO 2022 Japanese JIS X 0201-1989
50225	ISO 2022 Korean
50227	ISO 2022 Simplified Chinese
50229	ISO 2022 Traditional Chinese
50930	Japanese (Katakana) Extended
50931	US/Canada and Japanese
50933	Korean Extended and Korean
50935	Simplified Chinese Extended and Simplified Chinese
50936	Simplified Chinese
50937	US/Canada and Traditional Chinese
50939	Japanese (Latin) Extended and Japanese
51932	EUC - Japanese
51936	EUC - Simplified Chinese
51949	EUC - Korean
51950	EUC - Traditional Chinese
52936	HZ-GB2312 Simplified Chinese
54936	Windows XP: GB18030 Simplified Chinese (4 Byte)
57002	ISCII Devanagari
57003	ISCII Bengali
57004	ISCII Tamil
57005	ISCII Telugu
57006	ISCII Assamese
57007	ISCII Oriya
57008	ISCII Kannada
57009	ISCII Malayalam
57010	ISCII Gujarati
57011	ISCII Punjabi
65000	Unicode UTF-7
65001	Unicode UTF-8

The following is a list of valid code page identifiers for Mac OS only:


Identifier	Name
1	ASCII
2	NEXTSTEP
3	JapaneseEUC
4	UTF8
5	ISOLatin1
6	Symbol
7	NonLossyASCII
8	ShiftJIS
9	ISOLatin2
10	Unicode
11	WindowsCP1251
12	WindowsCP1252
13	WindowsCP1253
14	WindowsCP1254
15	WindowsCP1250
21	ISO2022JP
30	MacOSRoman
10	UTF16String
0x90000100	UTF16BigEndian
0x94000100	UTF16LittleEndian
0x8c000100	UTF32String
0x98000100	UTF32BigEndian
0x9c000100	UTF32LittleEndian
65536	Proprietary

LicenseInfo: Information about the current license.

When queried, this setting will return a string containing information about the license this instance of a class is using. It will return the following information:

Product: The product the license is for.
Product Key: The key the license was generated from.
License Source: Where the license was found (e.g., RuntimeLicense, License File).
License Type: The type of license installed (e.g., Royalty Free, Single Server).
Last Valid Build: The last valid build number for which the license will work.

MaskSensitive: Whether sensitive data is masked in log messages.

In certain circumstances it may be beneficial to mask sensitive data, like passwords, in log messages. Set this to True to mask sensitive data. The default is True.

This setting only works on these classes: AS3Receiver, AS3Sender, Atom, Client(3DS), FTP, FTPServer, IMAP, OFTPClient, SSHClient, SCP, Server(3DS), Sexec, SFTP, SFTPServer, SSHServer, TCPClient, TCPServer.

ProcessIdleEvents: Whether the class uses its internal event loop to process events when the main thread is idle.

If set to False, the class will not fire internal idle events. Set this to False to use the class in a background thread on Mac OS. By default, this setting is True.

SelectWaitMillis: The length of time in milliseconds the class will wait when DoEvents is called if there are no events to process.

If there are no events to process when do_events is called, the class will wait for the amount of time specified here before returning. The default value is 20.

UseInternalSecurityAPI: Whether or not to use the system security libraries or an internal implementation.

When set to False, the class will use the system security libraries by default to perform cryptographic functions where applicable.

Setting this configuration setting to True tells the class to use the internal implementation instead of using the system security libraries.

On Windows, this setting is set to False by default. On Linux/macOS, this setting is set to True by default.

To use the system security libraries for Linux, OpenSSL support must be enabled. For more information on how to enable OpenSSL, please refer to the OpenSSL Notes section.

MQTTSN Errors

UDP Errors


	104 UDP is already active.
	106 You cannot change the local_port while the class is active.
	107 You cannot change the local_host at this time. A connection is in progress.
	109 The class must be active for this operation.
	112 Cannot change MaxPacketSize while the class is active.
	113 Cannot change ShareLocalPort option while the class is active.
	114 Cannot change remote_host when UseConnection is set and the class active.
	115 Cannot change remote_port when UseConnection is set and the class is active.
	116 remote_port can't be zero when UseConnection is set. Please specify a valid service port number.
	117 Cannot change UseConnection while the class is active.
	118 Message can't be longer than MaxPacketSize.
	119 Message too short.
	434 Unable to convert string to selected CodePage

SSL Errors


	270 Cannot load specified security library.
	271 Cannot open certificate store.
	272 Cannot find specified certificate.
	273 Cannot acquire security credentials.
	274 Cannot find certificate chain.
	275 Cannot verify certificate chain.
	276 Error during handshake.
	280 Error verifying certificate.
	281 Could not find client certificate.
	282 Could not find server certificate.
	283 Error encrypting data.
	284 Error decrypting data.

TCP/IP Errors


	10004 [10004] Interrupted system call.
	10009 [10009] Bad file number.
	10013 [10013] Access denied.
	10014 [10014] Bad address.
	10022 [10022] Invalid argument.
	10024 [10024] Too many open files.
	10035 [10035] Operation would block.
	10036 [10036] Operation now in progress.
	10037 [10037] Operation already in progress.
	10038 [10038] Socket operation on non-socket.
	10039 [10039] Destination address required.
	10040 [10040] Message too long.
	10041 [10041] Protocol wrong type for socket.
	10042 [10042] Bad protocol option.
	10043 [10043] Protocol not supported.
	10044 [10044] Socket type not supported.
	10045 [10045] Operation not supported on socket.
	10046 [10046] Protocol family not supported.
	10047 [10047] Address family not supported by protocol family.
	10048 [10048] Address already in use.
	10049 [10049] Can't assign requested address.
	10050 [10050] Network is down.
	10051 [10051] Network is unreachable.
	10052 [10052] Net dropped connection or reset.
	10053 [10053] Software caused connection abort.
	10054 [10054] Connection reset by peer.
	10055 [10055] No buffer space available.
	10056 [10056] Socket is already connected.
	10057 [10057] Socket is not connected.
	10058 [10058] Can't send after socket shutdown.
	10059 [10059] Too many references, can't splice.
	10060 [10060] Connection timed out.
	10061 [10061] Connection refused.
	10062 [10062] Too many levels of symbolic links.
	10063 [10063] File name too long.
	10064 [10064] Host is down.
	10065 [10065] No route to host.
	10066 [10066] Directory not empty
	10067 [10067] Too many processes.
	10068 [10068] Too many users.
	10069 [10069] Disc Quota Exceeded.
	10070 [10070] Stale NFS file handle.
	10071 [10071] Too many levels of remote in path.
	10091 [10091] Network subsystem is unavailable.
	10092 [10092] WINSOCK DLL Version out of range.
	10093 [10093] Winsock not loaded yet.
	11001 [11001] Host not found.
	11002 [11002] Non-authoritative 'Host not found' (try again or check DNS setup).
	11003 [11003] Non-recoverable errors: FORMERR, REFUSED, NOTIMP.
	11004 [11004] Valid name, no data record (check DNS setup).