MQTT
mqtt publish <config> <topic> <payload>
Description
Publish a text with QoS 1, synchronously. Returns {topic, qos, bytes}
Publish a text with QoS 1, synchronously. Returns {topic, qos, bytes}
Parameters
config: The MQTT configuration as JSON: url (tcp://, mqtt://, ssl:// or mqtts://, port 1883 or 8883 by default, no credentials in it), client_id (generated if absent; needed with clean_session false), username, password (or password_env: the name of an environment variable), clean_session (true), timeout_ms (10000, from 100 to 600000, for each network step), keepalive (60 seconds), allow_plain (false: a password over tcp:// to a host other than localhost or 127.x.x.x is refused; no DNS request decides this). With TLS the certificate and the host name are checked: trust_store (a PEM or DER certificate file, PKCS12 or JKS, under the file access rules), trust_store_password (or trust_store_password_env), trust_store_type, or trust_all (false; true accepts any certificate, for a test only) - String - required
topic: The topic: 1 to 65535 bytes in UTF-8, without + or # or NUL - String - required
payload: The text, sent in UTF-8 - String - required
config: The MQTT configuration as JSON: url (tcp://, mqtt://, ssl:// or mqtts://, port 1883 or 8883 by default, no credentials in it), client_id (generated if absent; needed with clean_session false), username, password (or password_env: the name of an environment variable), clean_session (true), timeout_ms (10000, from 100 to 600000, for each network step), keepalive (60 seconds), allow_plain (false: a password over tcp:// to a host other than localhost or 127.x.x.x is refused; no DNS request decides this). With TLS the certificate and the host name are checked: trust_store (a PEM or DER certificate file, PKCS12 or JKS, under the file access rules), trust_store_password (or trust_store_password_env), trust_store_type, or trust_all (false; true accepts any certificate, for a test only) - String - required
topic: The topic: 1 to 65535 bytes in UTF-8, without + or # or NUL - String - required
payload: The text, sent in UTF-8 - String - required
admin
mqtt publish "{\"url\": \"tcp://127.0.0.1:1883\", \"username\": \"admin\", \"password_env\": \"MQTT_PASSWORD\"}" "sensors/room1/temp" "21.5"
mentdb
{"topic": "sensors/room1/temp", "qos": 1, "bytes": 4}
mqtt publish <config> <topic> <payload> <json_params>
Description
Publish with parameters: qos (0, 1 or 2; 1 by default), retain (false; true with an empty payload clears the retained message), encoding (utf-8, or base64: the payload is decoded and sent as bytes)
Publish with parameters: qos (0, 1 or 2; 1 by default), retain (false; true with an empty payload clears the retained message), encoding (utf-8, or base64: the payload is decoded and sent as bytes)
Parameters
config: The MQTT configuration as JSON: url (tcp://, mqtt://, ssl:// or mqtts://, port 1883 or 8883 by default, no credentials in it), client_id (generated if absent; needed with clean_session false), username, password (or password_env: the name of an environment variable), clean_session (true), timeout_ms (10000, from 100 to 600000, for each network step), keepalive (60 seconds), allow_plain (false: a password over tcp:// to a host other than localhost or 127.x.x.x is refused; no DNS request decides this). With TLS the certificate and the host name are checked: trust_store (a PEM or DER certificate file, PKCS12 or JKS, under the file access rules), trust_store_password (or trust_store_password_env), trust_store_type, or trust_all (false; true accepts any certificate, for a test only) - String - required
topic: The topic: 1 to 65535 bytes in UTF-8, without + or # or NUL - String - required
payload: The text or the base64 - String - required
json_params: The parameters - String - required
config: The MQTT configuration as JSON: url (tcp://, mqtt://, ssl:// or mqtts://, port 1883 or 8883 by default, no credentials in it), client_id (generated if absent; needed with clean_session false), username, password (or password_env: the name of an environment variable), clean_session (true), timeout_ms (10000, from 100 to 600000, for each network step), keepalive (60 seconds), allow_plain (false: a password over tcp:// to a host other than localhost or 127.x.x.x is refused; no DNS request decides this). With TLS the certificate and the host name are checked: trust_store (a PEM or DER certificate file, PKCS12 or JKS, under the file access rules), trust_store_password (or trust_store_password_env), trust_store_type, or trust_all (false; true accepts any certificate, for a test only) - String - required
topic: The topic: 1 to 65535 bytes in UTF-8, without + or # or NUL - String - required
payload: The text or the base64 - String - required
json_params: The parameters - String - required
admin
mqtt publish "{\"url\": \"tcp://127.0.0.1:1883\", \"username\": \"admin\", \"password_env\": \"MQTT_PASSWORD\"}" "sensors/room2/temp" "19.0" "{\"qos\": 2, \"retain\": true}"
mentdb
{"topic": "sensors/room2/temp", "qos": 2, "bytes": 4}
QoS 0 without any acknowledgement (fixed result: a real local Apache ActiveMQ Artemis 2.33.0)
admin
mqtt publish "{\"url\": \"tcp://127.0.0.1:1883\", \"username\": \"admin\", \"password_env\": \"MQTT_PASSWORD\"}" "sensors/room1/temp" "21.6" "{\"qos\": 0}"
mentdb
{"topic": "sensors/room1/temp", "qos": 0, "bytes": 4}
bytes that are not UTF-8 (fixed result: a real local Apache ActiveMQ Artemis 2.33.0)
admin
mqtt publish "{\"url\": \"tcp://127.0.0.1:1883\", \"username\": \"admin\", \"password_env\": \"MQTT_PASSWORD\"}" "sensors/raw" "//4Aaw==" "{\"encoding\": \"base64\", \"retain\": true}"
mentdb
{"topic": "sensors/raw", "qos": 1, "bytes": 4}
mqtt publish_batch <config> <json_rows>
Description
Publish a list of rows {topic, payload} on one connection, one after the other. Returns {sent, failed, not_attempted, errors}: failed counts every row not sent, not_attempted the part of them after a connection error, where the list stops; errors has at most 100 entries {row, error}, with row from 0. An invalid row does not stop the list. If the first connection fails the function fails
Publish a list of rows {topic, payload} on one connection, one after the other. Returns {sent, failed, not_attempted, errors}: failed counts every row not sent, not_attempted the part of them after a connection error, where the list stops; errors has at most 100 entries {row, error}, with row from 0. An invalid row does not stop the list. If the first connection fails the function fails
Parameters
config: The MQTT configuration as JSON: url (tcp://, mqtt://, ssl:// or mqtts://, port 1883 or 8883 by default, no credentials in it), client_id (generated if absent; needed with clean_session false), username, password (or password_env: the name of an environment variable), clean_session (true), timeout_ms (10000, from 100 to 600000, for each network step), keepalive (60 seconds), allow_plain (false: a password over tcp:// to a host other than localhost or 127.x.x.x is refused; no DNS request decides this). With TLS the certificate and the host name are checked: trust_store (a PEM or DER certificate file, PKCS12 or JKS, under the file access rules), trust_store_password (or trust_store_password_env), trust_store_type, or trust_all (false; true accepts any certificate, for a test only) - String - required
json_rows: The messages as a JSON array of objects (100000 at most). A value that is not a text is sent as JSON; numbers are kept exactly - String - required
config: The MQTT configuration as JSON: url (tcp://, mqtt://, ssl:// or mqtts://, port 1883 or 8883 by default, no credentials in it), client_id (generated if absent; needed with clean_session false), username, password (or password_env: the name of an environment variable), clean_session (true), timeout_ms (10000, from 100 to 600000, for each network step), keepalive (60 seconds), allow_plain (false: a password over tcp:// to a host other than localhost or 127.x.x.x is refused; no DNS request decides this). With TLS the certificate and the host name are checked: trust_store (a PEM or DER certificate file, PKCS12 or JKS, under the file access rules), trust_store_password (or trust_store_password_env), trust_store_type, or trust_all (false; true accepts any certificate, for a test only) - String - required
json_rows: The messages as a JSON array of objects (100000 at most). A value that is not a text is sent as JSON; numbers are kept exactly - String - required
admin
mqtt publish_batch "{\"url\": \"tcp://127.0.0.1:1883\", \"username\": \"admin\", \"password_env\": \"MQTT_PASSWORD\"}" "[{\"topic\": \"lines/1\", \"payload\": \"start\"}, {\"topic\": \"lines/#\", \"payload\": \"x\"}, {\"topic\": \"lines/2\", \"payload\": {\"state\": \"stop\"}}]"
mentdb
{"sent": 2, "failed": 1, "not_attempted": 0, "errors": [{"row": 1, "error": "the topic of a publish must not contain the wildcards + and #"}]}
mqtt publish_batch <config> <json_rows> <json_params>
Description
Publish a list with parameters: topic_field (topic), payload_field (payload), qos (1), retain (false), encoding (utf-8)
Publish a list with parameters: topic_field (topic), payload_field (payload), qos (1), retain (false), encoding (utf-8)
Parameters
config: The MQTT configuration as JSON: url (tcp://, mqtt://, ssl:// or mqtts://, port 1883 or 8883 by default, no credentials in it), client_id (generated if absent; needed with clean_session false), username, password (or password_env: the name of an environment variable), clean_session (true), timeout_ms (10000, from 100 to 600000, for each network step), keepalive (60 seconds), allow_plain (false: a password over tcp:// to a host other than localhost or 127.x.x.x is refused; no DNS request decides this). With TLS the certificate and the host name are checked: trust_store (a PEM or DER certificate file, PKCS12 or JKS, under the file access rules), trust_store_password (or trust_store_password_env), trust_store_type, or trust_all (false; true accepts any certificate, for a test only) - String - required
json_rows: The messages as a JSON array of objects (100000 at most). A value that is not a text is sent as JSON; numbers are kept exactly - String - required
json_params: The parameters - String - required
config: The MQTT configuration as JSON: url (tcp://, mqtt://, ssl:// or mqtts://, port 1883 or 8883 by default, no credentials in it), client_id (generated if absent; needed with clean_session false), username, password (or password_env: the name of an environment variable), clean_session (true), timeout_ms (10000, from 100 to 600000, for each network step), keepalive (60 seconds), allow_plain (false: a password over tcp:// to a host other than localhost or 127.x.x.x is refused; no DNS request decides this). With TLS the certificate and the host name are checked: trust_store (a PEM or DER certificate file, PKCS12 or JKS, under the file access rules), trust_store_password (or trust_store_password_env), trust_store_type, or trust_all (false; true accepts any certificate, for a test only) - String - required
json_rows: The messages as a JSON array of objects (100000 at most). A value that is not a text is sent as JSON; numbers are kept exactly - String - required
json_params: The parameters - String - required
admin
mqtt publish_batch "{\"url\": \"tcp://127.0.0.1:1883\", \"username\": \"admin\", \"password_env\": \"MQTT_PASSWORD\"}" "[{\"t\": \"lines/3\", \"v\": 12.5}]" "{\"topic_field\": \"t\", \"payload_field\": \"v\", \"qos\": 0}"
mentdb
{"sent": 1, "failed": 0, "not_attempted": 0, "errors": []}
mqtt receive <config> <topic_filter>
Description
Subscribe and read for at most 5 seconds, 100 messages and 16 MB, whichever comes first. Returns JSON rows {topic, payload, encoding, qos, retained, duplicate}; encoding is utf-8, or base64 when the payload is not valid UTF-8. No message gives []. If the connection is lost the rows already read are returned; without any row the function fails, as it does if the first message alone is larger than max_bytes. Messages refused after some rows add a field refused to the last row (see the top of the page)
Subscribe and read for at most 5 seconds, 100 messages and 16 MB, whichever comes first. Returns JSON rows {topic, payload, encoding, qos, retained, duplicate}; encoding is utf-8, or base64 when the payload is not valid UTF-8. No message gives []. If the connection is lost the rows already read are returned; without any row the function fails, as it does if the first message alone is larger than max_bytes. Messages refused after some rows add a field refused to the last row (see the top of the page)
Parameters
config: The MQTT configuration as JSON: url (tcp://, mqtt://, ssl:// or mqtts://, port 1883 or 8883 by default, no credentials in it), client_id (generated if absent; needed with clean_session false), username, password (or password_env: the name of an environment variable), clean_session (true), timeout_ms (10000, from 100 to 600000, for each network step), keepalive (60 seconds), allow_plain (false: a password over tcp:// to a host other than localhost or 127.x.x.x is refused; no DNS request decides this). With TLS the certificate and the host name are checked: trust_store (a PEM or DER certificate file, PKCS12 or JKS, under the file access rules), trust_store_password (or trust_store_password_env), trust_store_type, or trust_all (false; true accepts any certificate, for a test only) - String - required
topic_filter: The filter: + takes a whole level, # is the last level, ex: sensors/+/temp, sensors/# - String - required
config: The MQTT configuration as JSON: url (tcp://, mqtt://, ssl:// or mqtts://, port 1883 or 8883 by default, no credentials in it), client_id (generated if absent; needed with clean_session false), username, password (or password_env: the name of an environment variable), clean_session (true), timeout_ms (10000, from 100 to 600000, for each network step), keepalive (60 seconds), allow_plain (false: a password over tcp:// to a host other than localhost or 127.x.x.x is refused; no DNS request decides this). With TLS the certificate and the host name are checked: trust_store (a PEM or DER certificate file, PKCS12 or JKS, under the file access rules), trust_store_password (or trust_store_password_env), trust_store_type, or trust_all (false; true accepts any certificate, for a test only) - String - required
topic_filter: The filter: + takes a whole level, # is the last level, ex: sensors/+/temp, sensors/# - String - required
admin
mqtt receive "{\"url\": \"tcp://127.0.0.1:1883\", \"username\": \"admin\", \"password_env\": \"MQTT_PASSWORD\"}" "sensors/+/temp"
mentdb
[{"topic": "sensors/room2/temp", "payload": "19.0", "encoding": "utf-8", "qos": 1, "retained": true, "duplicate": false}]
mqtt receive <config> <topic_filter> <json_params>
Description
Read with parameters: qos (1; 2 is refused with clean_session false, as its state in memory would lose messages between two calls), max_messages (100, up to 100000), timeout_ms (5000: the whole reading, up to 600000), max_bytes (16 MB, up to 256 MB, on the sum of the payloads)
Read with parameters: qos (1; 2 is refused with clean_session false, as its state in memory would lose messages between two calls), max_messages (100, up to 100000), timeout_ms (5000: the whole reading, up to 600000), max_bytes (16 MB, up to 256 MB, on the sum of the payloads)
Parameters
config: The MQTT configuration as JSON: url (tcp://, mqtt://, ssl:// or mqtts://, port 1883 or 8883 by default, no credentials in it), client_id (generated if absent; needed with clean_session false), username, password (or password_env: the name of an environment variable), clean_session (true), timeout_ms (10000, from 100 to 600000, for each network step), keepalive (60 seconds), allow_plain (false: a password over tcp:// to a host other than localhost or 127.x.x.x is refused; no DNS request decides this). With TLS the certificate and the host name are checked: trust_store (a PEM or DER certificate file, PKCS12 or JKS, under the file access rules), trust_store_password (or trust_store_password_env), trust_store_type, or trust_all (false; true accepts any certificate, for a test only) - String - required
topic_filter: The filter: + takes a whole level, # is the last level, ex: sensors/+/temp, sensors/# - String - required
json_params: The parameters - String - required
config: The MQTT configuration as JSON: url (tcp://, mqtt://, ssl:// or mqtts://, port 1883 or 8883 by default, no credentials in it), client_id (generated if absent; needed with clean_session false), username, password (or password_env: the name of an environment variable), clean_session (true), timeout_ms (10000, from 100 to 600000, for each network step), keepalive (60 seconds), allow_plain (false: a password over tcp:// to a host other than localhost or 127.x.x.x is refused; no DNS request decides this). With TLS the certificate and the host name are checked: trust_store (a PEM or DER certificate file, PKCS12 or JKS, under the file access rules), trust_store_password (or trust_store_password_env), trust_store_type, or trust_all (false; true accepts any certificate, for a test only) - String - required
topic_filter: The filter: + takes a whole level, # is the last level, ex: sensors/+/temp, sensors/# - String - required
json_params: The parameters - String - required
admin
mqtt receive "{\"url\": \"tcp://127.0.0.1:1883\", \"username\": \"admin\", \"password_env\": \"MQTT_PASSWORD\"}" "sensors/raw" "{\"max_messages\": 1, \"timeout_ms\": 2000}"
mentdb
[{"topic": "sensors/raw", "payload": "//4Aaw==", "encoding": "base64", "qos": 1, "retained": true, "duplicate": false}]
all the tree (fixed result: a real local Apache ActiveMQ Artemis 2.33.0)
admin
mqtt receive "{\"url\": \"tcp://127.0.0.1:1883\", \"username\": \"admin\", \"password_env\": \"MQTT_PASSWORD\"}" "sensors/#" "{\"qos\": 2, \"max_messages\": 2, \"timeout_ms\": 1000}"
mentdb
[{"topic": "sensors/raw", "payload": "//4Aaw==", "encoding": "base64", "qos": 1, "retained": true, "duplicate": false}, {"topic": "sensors/room2/temp", "payload": "19.0", "encoding": "utf-8", "qos": 2, "retained": true, "duplicate": false}]
mqtt test <config>
Description
Try a connection. Returns {ok, latency_ms, error}: a broker that is stopped or refuses the credentials gives ok false and the reason; only an invalid configuration is an error of the function
Try a connection. Returns {ok, latency_ms, error}: a broker that is stopped or refuses the credentials gives ok false and the reason; only an invalid configuration is an error of the function
Parameters
config: The MQTT configuration as JSON: url (tcp://, mqtt://, ssl:// or mqtts://, port 1883 or 8883 by default, no credentials in it), client_id (generated if absent; needed with clean_session false), username, password (or password_env: the name of an environment variable), clean_session (true), timeout_ms (10000, from 100 to 600000, for each network step), keepalive (60 seconds), allow_plain (false: a password over tcp:// to a host other than localhost or 127.x.x.x is refused; no DNS request decides this). With TLS the certificate and the host name are checked: trust_store (a PEM or DER certificate file, PKCS12 or JKS, under the file access rules), trust_store_password (or trust_store_password_env), trust_store_type, or trust_all (false; true accepts any certificate, for a test only) - String - required
config: The MQTT configuration as JSON: url (tcp://, mqtt://, ssl:// or mqtts://, port 1883 or 8883 by default, no credentials in it), client_id (generated if absent; needed with clean_session false), username, password (or password_env: the name of an environment variable), clean_session (true), timeout_ms (10000, from 100 to 600000, for each network step), keepalive (60 seconds), allow_plain (false: a password over tcp:// to a host other than localhost or 127.x.x.x is refused; no DNS request decides this). With TLS the certificate and the host name are checked: trust_store (a PEM or DER certificate file, PKCS12 or JKS, under the file access rules), trust_store_password (or trust_store_password_env), trust_store_type, or trust_all (false; true accepts any certificate, for a test only) - String - required
admin
mqtt test "{\"url\": \"tcp://127.0.0.1:1883\", \"username\": \"admin\", \"password_env\": \"MQTT_PASSWORD\"}"
mentdb
{"ok": true, "latency_ms": 3, "error": null}
a port where no broker listens (fixed result: a real local Apache ActiveMQ Artemis 2.33.0)
admin
mqtt test "{\"url\": \"tcp://127.0.0.1:21999\", \"timeout_ms\": 1000}"
mentdb
{"ok": false, "latency_ms": 3, "error": "MQTT: cannot connect to the broker '127.0.0.1:21999'"}
bad credentials (fixed result: a real local Apache ActiveMQ Artemis 2.33.0)
admin
mqtt test "{\"url\": \"tcp://127.0.0.1:1883\", \"username\": \"admin\", \"password_env\": \"MQTT_WRONG_PASSWORD\"}"
mentdb
{"ok": false, "latency_ms": 3, "error": "MQTT: not authorized by the broker: check the username and the password"}