diff --git a/docs/en/modules/enduser-setup.md b/docs/en/modules/enduser-setup.md new file mode 100644 index 00000000..d86a2319 --- /dev/null +++ b/docs/en/modules/enduser-setup.md @@ -0,0 +1,47 @@ +# enduser setup Module +This module provides a simple way of configuring ESP8266 chips without using a serial interface or pre-programming WiFi credentials onto the chip. + +![](https://github.com/robertfoss/esp8266_nodemcu_wifi_setup/blob/images/screenshot.png?raw=true) + +After running [`enduser_setup.start()`](#enduser_setupstart) a portal like the above can be accessed through a wireless network called SetupGadget_XXXXXX. The portal is used to submit the credentials for the WiFi of the enduser. +After an IP address has been successfully obtained this module will stop as if [`enduser_setup.stop()`](#enduser_setupstop) had been called. + +## enduser_setup.start() + +Starts the captive portal. + +#### Syntax +`enduser_setup.start([onConfigured()], [onError(err_num, string)], [onDebug(string)])` + +#### Parameters + - `onConfigured()` callback will be fired when an IP-address has been obtained, just before the enduser_setup module will terminate itself + - `onError()` callback will be fired if an error is encountered. `err_num` is a number describing the error, and `string` contains a description of the error. + - `onDebug()` callback is disabled by default. It is intended to be used to find internal issues in the module. `string` contains a description of what is going on. + +#### Returns +`nil` + +#### Example +```lua +enduser_setup.start( + function() + print("Connected to wifi as:" .. wifi.sta.getip()) + end, + function(err, str) + print("enduser_setup: Err #" .. err .. ": " .. str) + end +); +``` + +## enduser_setup.stop() + +Stops the captive portal. + +#### Syntax +`enduser_setup.stop()` + +#### Parameters +none + +#### Returns +`nil` \ No newline at end of file diff --git a/docs/en/modules/mqtt.md b/docs/en/modules/mqtt.md new file mode 100644 index 00000000..30a3db35 --- /dev/null +++ b/docs/en/modules/mqtt.md @@ -0,0 +1,152 @@ +# MQTT Module + +The client adheres to version 3.1.1 of the [MQTT](https://en.wikipedia.org/wiki/MQTT) protocol. Make sure that your broker supports and is correctly configured for version 3.1.1. The client is backwards incompatible with brokers running MQTT 3.1. + +## mqtt.Client() + +Creates a MQTT client. + +#### Syntax +`mqtt.Client(clientid, keepalive, username, password, [cleansession])` + +#### Parameters +- `clientid` client ID +- `keepalive` keepalive seconds +- `username` user name +- `password` user password +- `cleansession` 0/1 for `false`/`true` + +#### Returns +MQTT client + +#### Example +```lua +-- init mqtt client with keepalive timer 120sec +m = mqtt.Client("clientid", 120, "user", "password") + +-- setup Last Will and Testament (optional) +-- Broker will publish a message with qos = 0, retain = 0, data = "offline" +-- to topic "/lwt" if client don't send keepalive packet +m:lwt("/lwt", "offline", 0, 0) + +m:on("connect", function(client) print ("connected") end) +m:on("offline", function(client) print ("offline") end) + +-- on publish message receive event +m:on("message", function(client, topic, data) + print(topic .. ":" ) + if data ~= nil then + print(data) + end +end) + +-- for TLS: m:connect("192.168.11.118", secure-port, 1) +m:connect("192.168.11.118", 1880, 0, function(client) print("connected") end) + +-- Calling subscribe/publish only makes sense once the connection +-- was successfully established. In a real-world application you want +-- move those into the 'connect' callback or make otherwise sure the +-- connection was established. + +-- subscribe topic with qos = 0 +m:subscribe("/topic",0, function(client) print("subscribe success") end) +-- publish a message with data = hello, QoS = 0, retain = 0 +m:publish("/topic","hello",0,0, function(client) print("sent") end) + +m:close(); +-- you can call m:connect again +``` + +# MQTT Client + + +## mqtt.client:close() + +Closes connection to the broker. + +#### Syntax +`mqtt:close()` + +#### Parameters +none + +#### Returns +`nil` + +## mqtt.client:connect() + +Connects to the broker specified by the given host, port, and secure options. + +#### Syntax +`mqtt:connect(host, port, secure, function(client))` + +#### Parameters +- `host` host, domain or IP (string) +- `port` broker port (number) +- `secure` 0/1 for `false`/`true`, default 0. [As per #539](https://github.com/nodemcu/nodemcu-firmware/issues/539#issuecomment-170298120) secure connections use TLS 1.2. +- `function(client)` call back function for when the connection was established + +#### Returns +`nil` + +## mqtt.client:lwt() + +Setup [Last Will and Testament](http://www.hivemq.com/blog/mqtt-essentials-part-9-last-will-and-testament) (optional). A broker will publish a message with qos = 0, retain = 0, data = "offline" to topic "/lwt" if client does not send keepalive packet. + +#### Syntax +`mqtt:lwt(topic, message, qos, retain)` + +#### Parameters +- `topic` the topic to publish to (string) +- `message` the message to publish, (buffer or string) +- `qos` QoS level, default 0 +- `retain` retain flag, default 0 + +#### Returns +`nil` + +## mqtt.client:on() + +Registers a callback function for an event. + +#### Syntax +`mqtt:on(event, function(client, [topic], [message]))` + +#### Parameters +- `event` can be "connect", "message" or "offline" +- `function(client, [topic], [message])` callback function. The first parameter is the client. If event is "message", the 2nd and 3rd param are received topic and message (strings). + +#### Returns +`nil` + +## mqtt.client:publish() + +Publishes a message. + +#### Syntax +`mqtt:publish(topic, payload, qos, retain, function(client))` + +#### Parameters +- `topic` the topic to publish to ([topic string](http://www.hivemq.com/blog/mqtt-essentials-part-5-mqtt-topics-best-practices)) +- `message` the message to publish, (buffer or string) +- `qos` QoS level, default 0 +- `retain` retain flag, default 0 +- `function(client)` callback fired when PUBACK received + +#### Returns +`nil` + +## mqtt.client:subscribe() + +Subscribes to one or several topics. + +#### Syntax +`mqtt:subscribe(topic, qos, function(client, topic, message))` + +#### Parameters +- `topic` a [topic string](http://www.hivemq.com/blog/mqtt-essentials-part-5-mqtt-topics-best-practices) +- `qos` QoS subscription level, default 0 +- `function(client, topic, message)` callback fired when message received + +#### Returns +`nil` \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index ad623ce3..9bbd81df 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -33,10 +33,12 @@ pages: - 'bit': 'en/modules/bit.md' - 'cjson': 'en/modules/cjson.md' - 'crypto': 'en/modules/crypto.md' - - 'gpio': 'en/modules/gpio.md' - - 'node': 'en/modules/node.md' + - 'enduser setup': 'en/modules/enduser-setup.md' - 'file': 'en/modules/file.md' + - 'gpio': 'en/modules/gpio.md' - 'i2c' : 'en/modules/i2c.md' + - 'node': 'en/modules/node.md' + - 'mqtt': 'en/modules/mqtt.md' - 'pwm' : 'en/modules/pwm.md' - 'rtcmem': 'en/modules/rtcmem.md' - 'rtctime': 'en/modules/rtctime.md'