mqtt support

Author: pelikhan

README.md

@@ -29,14 +29,38 @@ IO_FEED=feed
 IO_KEY=...
 ```
 
-## createData (REST)
+This extension uses the following settings:
 
-The createData function will upload a value to the Adafruit.io feed using the REST APIs
-and return the HTTP status code.
+-   IO_KEY: (required) access key
+-   IO_FEED: feed name
+-   IO_USER: io.adafruit.com user name
+-   IO_LAT: (optional) latitude (as a number)
+-   IO_LON: (optional) longitude (as a number)
+-   IO_ELE: (optional) elevation (as a number)
+
+## REST
+
+The createData function will upload a value to the Adafruit.io feed using the [REST APIs](https://io.adafruit.com/api/docs/#create-data) and return the HTTP status code.
 
 ```ts
 import { createData } from "devicescript-adafruit-io"
 const value = await temperature.reading.read()
 const status = await createData(value)
 console.log({ status })
 ```
+
+## MQTT
+
+This API connects to the [MQTT](https://io.adafruit.com/api/docs/mqtt.html#adafruit-io-mqtt-api)
+broker and let's you publish sensor data through the feed topics.
+
+```ts
+import {
+    publishData,
+    startAdafruitIOMQTTClient,
+} from "devicescript-adafruit-io"
+
+const client = await startAdafruitIOMQTTClient()
+
+await publishData(client, 456)
+```

src/http.ts

@@ -1,25 +1,25 @@
 import { fetch } from "@devicescript/net"
-import { FeedOptions, loadOptions } from "./options"
+import {
+    FeedOptions,
+    UserOptions,
+    loadFeedOptions,
+    loadUserOptions,
+} from "./options"
 
 /**
  * Creates a data point in a Adafruit.io feed using
  * the {@link https://io.adafruit.com/api/docs/#create-data | REST API}
  *
- * This extension uses the following settings:
- *
- * - IO_KEY: (required) access key
- * - IO_FEED: feed name
- * - IO_USER: io.adafruit.com user name
- * - IO_LAT: (optional) latitude (as a number)
- * - IO_LON: (optional) longitude (as a number)
- * - IO_ELE: (optional) elevation (as a number)
- *
  * @param value numerical value to upload
- * @param options optional latitude longitude
+ * @param options optional settings
  * @returns HTTP status code
  */
-export async function createData(value: number, options?: FeedOptions) {
-    const { key, feed, user, lat, lon, ele } = await loadOptions(options)
+export async function createData(
+    value: number,
+    options?: UserOptions & FeedOptions
+) {
+    const { key, user } = await loadUserOptions(options)
+    const { feed, lat, lon, ele } = await loadFeedOptions(options)
 
     const url = `https://io.adafruit.com/api/v2/${user}/feeds/${feed}/data`
     const headers = { "X-AIO-Key": key, "Content-Type": "application/json" }

src/index.ts

@@ -1,2 +1,3 @@
 export * from "./options"
 export * from "./http"
+export * from "./mqtt"

src/main.ts

@@ -1,3 +1,7 @@
-import { createData } from "."
+import { createData, publishData, startAdafruitIOMQTTClient } from "."
 
 await createData(123)
+
+const client = await startAdafruitIOMQTTClient()
+
+await publishData(client, 456)

src/mqtt.ts

@@ -0,0 +1,43 @@
+import { MQTTClient, startMQTTClient } from "@devicescript/net"
+import {
+    FeedOptions,
+    UserOptions,
+    loadFeedOptions,
+    loadUserOptions,
+} from "./options"
+
+/**
+ * Starts a MQTT client for the  Adafruit.io broker
+ * @see {@link https://io.adafruit.com/api/docs/mqtt.html#adafruit-io-mqtt-api}
+ */
+export async function startAdafruitIOMQTTClient(options?: UserOptions) {
+    const { user, key } = await loadUserOptions(options)
+    const client = await startMQTTClient({
+        username: user,
+        password: key,
+        host: "io.adafruit.com",
+        port: 8883,
+    })
+    ;(client as any).__user = user
+    return client
+}
+
+/**
+ * Publishes a data entry on the given feed
+ * @see {@link https://io.adafruit.com/api/docs/mqtt.html#adafruit-io-mqtt-api}
+ * @param client MQTT client opened with startAdafruitIOMQTTClient
+ */
+export async function publishData(
+    client: MQTTClient,
+    value: number | Record<string, number>,
+    options?: FeedOptions
+) {
+    const { feed, lon, lat, ele } = await loadFeedOptions(options)
+    const user = (client as any).__user as string
+    const topic = `${user}/f/${feed}/json`
+    const payload: any = { value }
+    if (lon !== undefined) payload.lon = lon
+    if (lat !== undefined) payload.lat = lat
+    if (ele !== undefined) payload.ele = ele
+    await client.publish(topic, payload)
+}

src/options.ts

@@ -1,36 +1,55 @@
 import { readSetting } from "@devicescript/settings"
 
+/**
+ * Adafruit.io configuration options
+ */
+export interface UserOptions {
+    user?: string
+}
+
+/**
+ * Merges the passed options and the options in the settings
+ * - IO_KEY: (required) access key
+ * - IO_USER: io.adafruit.com user name
+ * @param options
+ * @returns a valid option object, including the key
+ * @throws Error missing user or feed information
+ */
+export async function loadUserOptions(
+    options?: UserOptions
+): Promise<UserOptions & { key: string }> {
+    const key = await readSetting("IO_KEY")
+    if (!key) throw new Error("Adafruit.io: missing secret IO_KEY")
+    let { user } = options || {}
+    user = user || (await readSetting("IO_USER"))
+    if (!user) throw new Error("Adafruit.io: missing setting IO_USER")
+    return { user, key }
+}
+
 /**
  * Adafruit.io configuration options
  */
 export interface FeedOptions {
     feed?: string
-    user?: string
     lat?: number
     lon?: number
     ele?: number
 }
 
 /**
  * Merges the passed options and the options in the settings
- * - IO_KEY: (required) access key
  * - IO_FEED: feed name
- * - IO_USER: io.adafruit.com user name
  * - IO_LAT: (optional) latitude (as a number)
  * - IO_LON: (optional) longitude (as a number)
  * - IO_ELE: (optional) elevation (as a number)
  * @param options
  * @returns a valid option object, including the key
  * @throws Error missing user or feed information
  */
-export async function loadOptions(
+export async function loadFeedOptions(
     options?: FeedOptions
-): Promise<FeedOptions & { key: string }> {
-    const key = await readSetting("IO_KEY")
-    if (!key) throw new Error("Adafruit.io: missing secret IO_KEY")
-    let { feed, user, lat, lon, ele } = options || {}
-    user = user || (await readSetting("IO_USER"))
-    if (!user) throw new Error("Adafruit.io: missing setting IO_USER")
+): Promise<FeedOptions> {
+    let { feed, lat, lon, ele } = options || {}
     feed = feed || (await readSetting("IO_FEED"))
     if (!feed) throw new Error("Adafruit.io: missing setting IO_FEED")
 
@@ -39,9 +58,7 @@ export async function loadOptions(
     ele = ele || (await readSetting<number>("IO_ELE"))
 
     return {
-        key,
         feed,
-        user,
         lat,
         lon,
         ele,