From 1d382b625f539767a5e3d36557f24cf49acb91d0 Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Tue, 27 Aug 2019 08:08:09 -0600 Subject: [PATCH 1/3] WIP mqtt.to documentation --- .../reference/flux/functions/mqtt/_index.md | 22 ++++ .../v2.0/reference/flux/functions/mqtt/to.md | 110 ++++++++++++++++++ 2 files changed, 132 insertions(+) create mode 100644 content/v2.0/reference/flux/functions/mqtt/_index.md create mode 100644 content/v2.0/reference/flux/functions/mqtt/to.md diff --git a/content/v2.0/reference/flux/functions/mqtt/_index.md b/content/v2.0/reference/flux/functions/mqtt/_index.md new file mode 100644 index 000000000..384e4e692 --- /dev/null +++ b/content/v2.0/reference/flux/functions/mqtt/_index.md @@ -0,0 +1,22 @@ +--- +title: Flux MQTT package +list_title: MQTT package +description: > + The Flux MQTT package provides functions for working with MQTT protocol. + Import the `mqtt` package. +menu: + v2_0_ref: + name: MQTT + parent: Flux packages and functions +weight: 202 +v2.0/tags: [functions, mqtt, package] +--- + +MQTT Flux functions provide tools for working with Message Queuing Telemetry Transport (MQTT) protocol. +Import the `mqtt` package: + +```js +import "mqtt" +``` + +{{< children type="functions" show="pages" >}} diff --git a/content/v2.0/reference/flux/functions/mqtt/to.md b/content/v2.0/reference/flux/functions/mqtt/to.md new file mode 100644 index 000000000..6fbb68fee --- /dev/null +++ b/content/v2.0/reference/flux/functions/mqtt/to.md @@ -0,0 +1,110 @@ +--- +title: mqtt.to() function +description: > + The `mqtt.to()` function outputs data to an MQTT broker using MQTT protocol. +menu: + v2_0_ref: + name: mqtt.to + parent: MQTT +weight: 202 +--- + +The `mqtt.to()` function outputs data to an MQTT broker using MQTT protocol. + +_**Function type:** Output_ + +```js +import "mqtt" + +mqtt.to( + broker: "tcp://localhost:8883", + topic: "example-topic", + message: "", + qos: 0, + clientid: "flux-mqtt", + username: "username", + password: "password", + name: "name-example", + timeout: 1s, + timeColumn: "_time", + tagColumns: ["tag1", "tag2"], + valueColumns: ["_value"] +) +``` + +## Parameters + +### broker +The MQTT broker connection string. + +_**Data type: String**_ + +### topic +The MQTT topic to send data to. + +_**Data type: String**_ + +### message +placeholder + +_**Data type: String**_ + +### qos +The [MQTT Quality of Service (QoS)](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901103) level. +Values range from `[0-2]`. + +_**Data type: Integer**_ + +### clientid +The MQTT client ID. + +_**Data type: String**_ + +### username +The username to send to the MQTT Broker. + +_**Data type: String**_ + +### password +The password to send to the MQTT Broker. + +_**Data type: String**_ + +### name +placeholder + +_**Data type: String**_ + +### timeout +placeholder +Defaults to `1s` + +_**Data type: Duration**_ + +### timeColumn +placeholder +Defaults to `"_time"`. + +_**Data type: String**_ + +### tagColumns +placeholder +Defaults to `[]`. + +_**Data type: Array of strings**_ + +### valueColumns +placeholder +Defaults to `["_value"]`. + +_**Data type: Array of strings**_ + + +## Examples + +### Send data to an MQTT endpoint +```js +import "mqtt" + +// ... +``` From dcf34b5aed46db7845bccca23a0a4a0810a03b7d Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Wed, 28 Aug 2019 09:42:43 -0600 Subject: [PATCH 2/3] documented the mqtt.to function, resolves #362 --- .../reference/flux/functions/mqtt/_index.md | 1 + .../v2.0/reference/flux/functions/mqtt/to.md | 48 +++++++++++++------ 2 files changed, 34 insertions(+), 15 deletions(-) diff --git a/content/v2.0/reference/flux/functions/mqtt/_index.md b/content/v2.0/reference/flux/functions/mqtt/_index.md index 384e4e692..2b53b4519 100644 --- a/content/v2.0/reference/flux/functions/mqtt/_index.md +++ b/content/v2.0/reference/flux/functions/mqtt/_index.md @@ -10,6 +10,7 @@ menu: parent: Flux packages and functions weight: 202 v2.0/tags: [functions, mqtt, package] +draft: true --- MQTT Flux functions provide tools for working with Message Queuing Telemetry Transport (MQTT) protocol. diff --git a/content/v2.0/reference/flux/functions/mqtt/to.md b/content/v2.0/reference/flux/functions/mqtt/to.md index 6fbb68fee..d91664b98 100644 --- a/content/v2.0/reference/flux/functions/mqtt/to.md +++ b/content/v2.0/reference/flux/functions/mqtt/to.md @@ -7,6 +7,7 @@ menu: name: mqtt.to parent: MQTT weight: 202 +draft: true --- The `mqtt.to()` function outputs data to an MQTT broker using MQTT protocol. @@ -19,7 +20,7 @@ import "mqtt" mqtt.to( broker: "tcp://localhost:8883", topic: "example-topic", - message: "", + message: "Example message", qos: 0, clientid: "flux-mqtt", username: "username", @@ -45,13 +46,20 @@ The MQTT topic to send data to. _**Data type: String**_ ### message -placeholder +The message or payload to send to the MQTT broker. +The default payload is all output tables. + +{{% note %}} +When you specify a message, the function sends only the message string to the MQTT broker. +It does not send any output tables. +{{% /note %}} _**Data type: String**_ ### qos The [MQTT Quality of Service (QoS)](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901103) level. Values range from `[0-2]`. +Default is `0`. _**Data type: Integer**_ @@ -61,50 +69,60 @@ The MQTT client ID. _**Data type: String**_ ### username -The username to send to the MQTT Broker. +The username to send to the MQTT broker. +This is only necessary when the MQTT broker requires authentication. _**Data type: String**_ ### password -The password to send to the MQTT Broker. +The password to send to the MQTT broker. +This is only necessary when the MQTT broker requires authentication. _**Data type: String**_ ### name -placeholder +The name for the MQTT message _(Optional)_. _**Data type: String**_ ### timeout -placeholder -Defaults to `1s` +The MQTT connection timeout. +Default is `1s` _**Data type: Duration**_ ### timeColumn -placeholder -Defaults to `"_time"`. +The column to use as time values in the output line protocol. +Default is `"_time"`. _**Data type: String**_ ### tagColumns -placeholder -Defaults to `[]`. +The columns to use as tag sets in the output line protocol. +Default is `[]`. _**Data type: Array of strings**_ ### valueColumns -placeholder -Defaults to `["_value"]`. +The columns to use as field values in the output line protocol. +Default is `["_value"]`. _**Data type: Array of strings**_ - ## Examples ### Send data to an MQTT endpoint ```js import "mqtt" -// ... +from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => r._measurement == "airSensor") + |> mqtt.to( + broker: "tcp://localhost:8883", + topic: "air-sensors", + clientid: "sensor-12a4", + tagColumns: ["sensorID"], + valueColumns: ["_value"] + ) ``` From 5fc3d439472c50cb4687e7f36b0708b6999a7405 Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Wed, 28 Aug 2019 10:41:41 -0600 Subject: [PATCH 3/3] updated mqtt.to to address PR feedback --- content/v2.0/reference/flux/functions/mqtt/to.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/content/v2.0/reference/flux/functions/mqtt/to.md b/content/v2.0/reference/flux/functions/mqtt/to.md index d91664b98..e67566895 100644 --- a/content/v2.0/reference/flux/functions/mqtt/to.md +++ b/content/v2.0/reference/flux/functions/mqtt/to.md @@ -47,11 +47,11 @@ _**Data type: String**_ ### message The message or payload to send to the MQTT broker. -The default payload is all output tables. +The default payload is an output table. +If there are multiple output tables, it sends each table as a separate MQTT message. {{% note %}} -When you specify a message, the function sends only the message string to the MQTT broker. -It does not send any output tables. +When you specify a message, the function sends the message string only (no output table). {{% /note %}} _**Data type: String**_ @@ -70,24 +70,26 @@ _**Data type: String**_ ### username The username to send to the MQTT broker. -This is only necessary when the MQTT broker requires authentication. +Username is only required if the broker requires authentication. +If you provide a username, you must provide a [password](#password). _**Data type: String**_ ### password The password to send to the MQTT broker. -This is only necessary when the MQTT broker requires authentication. +Password is only required if the broker requires authentication. +If you provide a password, you must provide a [username](#username). _**Data type: String**_ ### name -The name for the MQTT message _(Optional)_. +_(Optional)_ The name for the MQTT message. _**Data type: String**_ ### timeout The MQTT connection timeout. -Default is `1s` +Default is `1s`. _**Data type: Duration**_