ESP32 Nodes, Sensors & Output

[papa]

            ESP32 Nodes, Sensors & Output

The following requires use of the ESP32 programming, introduction, & customization in this thread. (Go there for the latest code, initial customization, usable pins, etc.) This present thread gives further customization & documentation for ESP32 nodes with sensors & output.

Most of the initial customization in the other thread is now headed by "//-----Generally customize this section only once----" That is, generally set that code & leave it alone.

    The ESP32 Nodes sketch has a new heading that reads
// For EACH new node, change the rest of the customization section
// from here to "=======End of Customization for Now ==="

In that section, when you start a new node ... 1) change the nodeId & 2) deactivate ALL the defines in that section. That is, in that section, have "// " (without quotes) at the start of every line with #define. (This avoids possibly interfering code left from a previous node.)
 
Then 3) edit the defines for the new node. When I write "activate a define," delete any // that starts the line.

Note: So far it seems that Arduino IDE Tools/Board can often be set to ESP32 Dev Module. Decreasing upload speed may help with uploading.

        Next, Node with [Push] Button "Sensor" on Sparkfun ESP32 Thing

[papa]

            Node with [Push] Button "Sensor" on Sparkfun ESP32 Thing

A node can be programmed to detect the press of a push button & send a MQTT message. For now, we'll just detect. Later customization will have a node act on that detection.

On the Sparkfun ESP32 Thing, we'll use a small board button connected to pin 0 (zero) & labelled with a tiny 0. (The other small button is labelled Rst for reset.)

For Button Detect, Node Customization in the ESP32_nodes sketch:

Find & activate the line #define BUTTON (Remember: delete any // that starts the line).
        Find the line with #define BTN & edit it to #define BTN 0            << 0 is zero

Remember: The rest of #define lines in the customization section should be deactivated (start with // ).

PS If you want to see how this node's code works, search for "#ifdef BUTTON"

In short, the sketch setup code pulls up the button pin to 1 or HIGH. Pushing down the button connects the pin to GND giving the button pin 0 (zero) the value of 0 (zero) or LOW.

Via USB, connect the node to Arduino IDE & upload the customized sketch.

            Next, Plain [Push] Button Serial Monitor results on Sparkfun ESP32 Thing:

[papa]

                    Plain [Push] Button Serial Monitor results on Sparkfun ESP32 Thing:

                            (After uploading open the Arduino IDE Serial Monitor.)

Node 36 Version ESP32_nodes_n006B MQCON 5 Btn 0
Connecting to XXX
...
WiFi connected
IP address: 192.168.10.113
Connect to MQTT broker...connected

topic home/esp_gw/nb/node36/dev99 value:NODE 36 WAKEUP: ESP_36

topic home/esp_gw/nb/node36/dev02 value:-38
topic home/esp_gw/nb/node36/dev10 value:192.168.10.113
topic home/esp_gw/nb/node36/dev40 value:up                            [intial pin 0 state, pulled up high ]
push button = 0                                                                        [pin 0 becomes 0 or low...
topic home/esp_gw/nb/node36/dev40 value:dwn                            [since button pushed down ]
push button = 1                                                                        [pin 0 becomes 1 or high ...
topic home/esp_gw/nb/node36/dev40 value:up                                [since button released up]

            Next, BUTTON on HiLetgo OLED ESP32 Board

[papa]

        BUTTON on HiLetgo OLED ESP32 Board & Other Boards

This board has onboard push buttons, but they don't seem connected to any pins exposed on the edge of the board. So I found a push button with cables. I connected the cables to the board's pin 2 & a GND.

                    Node Customizing:

Deactivate (//) all customizing #defines from before. Customize thus:
                                                                    #define BUTTON
    (changes from Sparkfun Thing):
#define MQCON 12                              (instead of #define MQCON 5
#define BTN 2                              (instead of #define BTN 0).

At Arduino IDE Tools/Board menu, choose ESP32 Arduino/Wemos Lolin32 or ESP32 Arduino/ESP32 Dev Module.  Connect board to USB. Upload. Open Serial Monitor.

            Serial Monitor Results on HiLetgo OLED ESP32 Board:

Same as for Sparkfun Thing above, except MQCON 12, Btn 2, & different IP.

            BUTTON on Other ESP32 Boards

Adapt based on the above approaches to Sparkfun ESP32 Thing & HiLetgo OLED ESP32 Board. Also see about usable ESP32 pins in this post.

[papa]

            Connecting ESP32 MQTT Nodes to OpenHAB

As said before, the ESP32 MQTT Nodes we are creating are able to work with openHAB, an open source automation platform.

This requires installing a MQTT broker on what will be the openHAB hosting computer. For this, see two posts starting here.

To learn about & install openHAB, see the helpful official openHAB site.   Linux install.  Raspberry PI install.   First Steps.

Also see my posts starting here. (My posts may be somewhat dated. When in doubt, follow the official site.)

See Adding Things - Advanced because our nodes use MQTT & the MQTT binding does not support automatic discovery.

     You can avoid the JSONpath transformation for now. Go to Create the Bridge Thing which includes installing the MQTT Binding & connecting to the MQTT broker.

                See my notes here & two posts starting here.

Below I'll begin to document configuring openHAB to connect with the ESP32 nodes we create.

        Next, openHAB terms: Thing, Channel, Binding, Bridge, Item

[papa]

        OpenHAB Key Terms: Thing, Channel, Binding, Bridge, Item

This short thread introduces the above terms that are key to our MQTT nodes communicating with openHAB.

As shown above, via MQTT messaging to our MQTT broker (Mosquitto), our nodes are publishing topics & values. For example, in this post above, node 36 publishes the value -38 to the topic home/esp_gw/nb/node36/dev02.  Dev02 (device 2) is where the node's software tracks RSSI or radio signal strength for the WiFi connection in this case.

Below (using the identified key terms), we'll enable openHAB to communicate with the MQTT topics that the node offers. Often the communication is from node to openHAB & sometimes it's openHAB to node communication.

        To Be Continued

[papa]

            Start Configuring OpenHAB for ESP32 Nodes

Make sure openHAB is running & that you are logged in to the openHAB dashboard. See posts starting here.

In the openHAB dashboard, go to Settings/Add-ons/Bindings

There make sure that you've installed the MQTT binding.

To install missing bindings: in the lower right, click the blue disc icon with a plus (+) sign.

            Next, Configure a Bridge for the MQTT Binding

[papa]

            Configure a Bridge for the MQTT Binding

This presupposes you have installed the Mosquitto MQTT messaging service.

Unlike for most other bindings, you must configure a Bridge related to the MQTT binding.

At the bottom right of localhost:8080/settings/things/   click the + icon in a blue disc (Add Thing)

Click MQTT Broker.  Notes: The System MQTT Broker is NOT recommended. Only one MQTT Bridge can be installed.

        Required configuration parameters are:

host: The IP/Hostname of the MQTT broker (IP address of computer hosting openHAB & Mosquitto MQTT broker).
port: The optional port of the MQTT broker. The typical port is 1883.
secure: Uses TLS/SSL to establish a secure connection to the broker. Can be true or false. Defaults to false.

    Depends on if you configure Mosquitto to require ID / password.

            Next: Create a Thing for an ESP32 Node

[papa]

            Create a Thing for an ESP32 Node

The following assumes how I built & programmed an ESP32 Node (Node36)  (See near the top of this thread.)

        This is how I created a Node36 Thing that will help communicate with the Node.

At the bottom right of localhost:8080/settings/things/   I clicked the + icon in a blue disc (Add Thing)

Click MQTT Binding.     Click Generic MQTT Thing

Leave these fields as is:   Unique ID & Identifier

For Label, I changed "Generic MQTT Thing" to Node36 (Change if your node's ID is different.)

For Location (one way to display devices), put a physical location name or leave blank.

      (Unlike some parameters, Location can be added/changed later.)

Click the Bridge field & select MQTT Broker.    Click [Create Thing]

Hope to see a [green Online button].

        Next: Create Channels for an ESP32 Node.

[papa]

            Create Node36 Channel for a Node's Device 2 (RSSI)

See this post. We're making a channel for the MQTT topic home/esp_gw/nb/node36/dev02

Logged in to your openHAB configuration, go to localhost:8080/settings/things/

In the listed Things, click Node36. Then click the [channels tab] near the top.

Near the bottom, click Add Channel.

        In the Add Channel Window, fill the fields with configs:

Channel identifier Node36Channel02
    ^^ arbitrary ? as long as we match it in a linked Item (see below)

Label Node36_RSSI
    ^^ arbitrary ?, make it useful for yourself, but not too long

Channel type Text Value
   ^^ choose type compatible with the device/channel data type
 
MQTT State Topic home/esp_gw/nb/node36/dev02
MQTT Command Topic [leave blank]

        Click [Create] to save your configs

Hint: The openHAB dashboard displays Things in alphabetical order, but displays a Thing's channels in the order they are created. So you might create Things as you need them. But if you like a Thing's channels in neater alphanumerical order, create them in that order & create all you may eventually use. (It should hurt nothing if they are not used.)

            Next: Create Item to Link to Node36's Channel 02

[papa]

            Dashboard Configuring an Item for Linking to Node36's Channel 02

I use the openHAB Dashboard to create Things & their channels. I use my existing & expanding .items files for Item configuration.

Caution: One can use both methods (on different items), but that could get confusing. To edit or delete an item, we must use the same method that created the item.

If you generally want to use Dashboard configuration, perhaps the following will be helpful.  Use ONLY ONE method to create the item.

    To create the Item, go to the Dashboard's settings/items/
At the lower right, click the "+" in a blue disc & then click "Add item"

        Complete the following fields:
Name: Node36RSSI        Label for display: Node36rssi
    Type: String        Category: [optional, icon for displays on some user interface displays]

        Click "Create" & be returned to the Items list.

In the Items list, click on the Node36RSSI Item & then click on Add Metadata

Click State Description.  Leave top field as Read only.

       In the Pattern field, enter        %s db

This will display the RSSI value followed by "db" (for decibels, an RSSI unit of measure)

          At the upper right, click Save

        To link the Node36RSSI Item, near the bottom click on Add Link.

Click on "Thing"         Scroll down to & select Node36.

  Then near the bottom, select Node36_RSSI ... Channel02(String)

For Profile, leave or choose Default.     At the bottom, click on the Link button in a blue box

This returns us to the main Node36RSSI Item screen.  Look at the field just below the top brightly-colored rectangle.

If our Node36 is programmed & powered, that field should display the Node36's RSSI, e.g. -62 db.

            ===========================

        To delete an Item created on the Dashboard, for example ...

on the main Node36RSSI Item screen, click the field just under "Channel Links"

        At the middle left, click the Unlink in red letters, then OK.

Then at the bottom, click Remove Item, then OK

            Next: Create The Same Item via a Text Config File
   

[papa]

        Create Item to Link to Node36's Channel 02,

            My Preference: Text Config File

Remember: Use only one method to create & edit an Item (Dashboard OR .items file) NOT BOTH.

This method both creates the Item AND links it to the Node36 Thing's Channel 02.

In openHAB's items folder (Linux   /etc/openhab/items), have an .items file to hold the Node36 Items. Mine is called ESP32.items, but the name before the .items tag is up to you.

        The RSSI (channel 02) Item takes the form:
String Node36RSSI "Node36rssi [%s db]"  { channel="Node36channelUID" }

Go to localhost:8080/settings/things/
    Click on the Listed Node36 Thing        Click on the [channels] tab
After the Node36_RSSI channel is a small stacked pages icon.
    Click on that icon to copy the channel UID

       Into the Item, paste that channel UID in place of Node36channelUID color-coded above.

For example, my channel's UID is

       mqtt:topic:c08f02ca8d:3f938be488:Node36Channel02

        So my Item (your channel UID for the Item will be different) is

String Node36RSSI "Node36rssi [%s db]"  { channel="mqtt:topic:c08f02ca8d:3f938be488:Node36Channel02" }

For display purposes only, go to localhost:8080/settings/items/Node36RSSI

        Look at the field just below the top brightly-colored rectangle.
If our Node36 is programmed & powered, that field should display the Node36's RSSI, e.g. -62 db.

                =========================================

       The above is somewhat involved, but the rest of Node36 channel links are almost the same, except the last 2 characters.

For example, my Item for Node36 version (device 03) would end with the following channel link:
     { channel="mqtt:topic:c08f02ca8d:3f938be488:Node36Channel03" }    << corrected

            Next: Display Node36's RSSI Data on HABPanel
   

[papa]

            Preparing to Display an Item's Data

One way to use the data collected in the Item named Date is to displaying it.

        OpenHAB 3's apps for displaying Items include:

1) BasicUI, a simpler one

2) HABPanel, which is more flexible & more efficient with screen real estate

        At the least, make sure HABPanel is installed:

Go to localhost:8080/settings/addons/ui

             At the lower right, click on + then click the app's name & at the bottom, click on [ Install ].

        Next: Efficiently Display an Item's Data on HABPanel

[papa]

        Efficiently Display an Item's Data on HABPanel

Go to the browser address localhost:8080. At the upper right are two small icons, a pencil & a "page." Hovering the mouse pointer over the pencil shows "Edit Home Page." Over the "page," shows "Other apps." Click on the "Other apps" icon & then click on HABPanel. The browser address becomes "http://localhost:8080/habpanel/"

The first time you use HABPanel, click the gear icon at the upper right. At the middle left, click on "Add new dashboard." For the new dashboard, enter a Name, perhaps "Main" & click OK.

Hover the mouse pointer over "Main" at the upper left. Click on the small pencil icon (edit dashboard) that appears. At the upper right, click on the [Add Widget] button.

In Add Widget, choose Dummy (useful for text).

In the new widget window at the upper right, click the 3 stacked dots. Choose Edit. Enter a Name, perhaps RSSInode36. In the openHAB Item field, choose the desired Item. You can click the drop down icon & scroll down to the Item named Node36RSSI. OR you can enter Node36RSSI in the search box. Either way, click on the Node36RSSI Item listed. In the Unit field put "db" (without quotes). Scroll to the bottom of the Edit Widget Window & click [Save].

Click the [Run] button to see "RSSInode36" plus a value like "-62db  in the Main dashboard.

        Display Item Data on HABPanel, Continued

[papa]

            Display Item Data on HABPanel, Continued

Later by clicking the pencil icon that will appear next to Main, you can add other widgets to the Main dashboard.

By clicking the pencil icon, you can also Edit widget settings: You can change the RSSInode36 widget's size & shape by dragging the widget's lower right corner. You can change it's location on the dashboard by clicking on the widget's upper left corner & then dragging.

After making changes, click the dashboard's [Run] button.

Now you can go directly to your HABPanel by entering the browser address: http://localhost:8080/habpanel/

OH 3's HABPanel via the OH 3 Dashboard seems to work much the same as OH 2.5.x's via OH 2's PaperUI. The opening browser addresses are just a little different. With the slight differences in mind, this thread (which I may update later) might help you do more with HABPanel.

        Why Use Text Files to Create & Link Items?

[papa]

        Why Use Text Files to Create & Link Items?

In the above posts, I was using the Dashboard to gain necessary info for creating & linking Items & then using that info in a text file of Items. Why not just use the Dashboard as I did in this post?

If I was starting at the beginning & had no Items already, I might use the Dashboard to create items. However, I have many items in text files. So I used the Dashboard to get correct channel linkages & use search & replace to migrate from OH 2.5.x format to OH 3 format.  To make new items, I can copy & paste & edit in .items files. I can group related items into .items files that have descriptive names.

If I put the correct channel linkages in Items, I only need to refresh the Dashboard in the browser & then a Thing's channels will automatically show themselves as linked to their matching item. Otherwise, I'd have to do more Dashboard clicking to link Items & channels.

Dashboard configuration of Items & their links may be best for you.  So far, I believe I'll stay with .items text files.

    Next, Node with BUTTONIO Options

[papa]

        Node with BUTTONIO (push button action changes ACTOR pin) on Sparkfun ESP32 Thing

Code similar to BUTTON above detects change in push button, but now such change also changes the state of the ACTOR pin.

As described here, I prepared an LED with an 100 ohm resistor.  Wiring: I connected the resistor lead to the board's pin 16 & the plain wire lead to a board GND.

        Node customizing on Sparkfun Thing:
Deactivate (//) all customizing #defines from before (esp. BUTTON). Customize thus:
       Activate (no //) & match:
#define MQCON 5          #define BUTTONIO      #define BTN 0
    #define ACTOR                  #define ACT1 16

Connect the board to USB & upload from Arduino IDE. Pushing the button 0 toggles the LED on & off. (Relays or other low power devices could be toggled this way.)

                    Note: After each push button press, the node code disregards presses for 2 seconds (debouncing).

        Next BUTTONIO Serial Monitor results on Sparkfun Thing

[papa]

        BUTTONIO Serial Monitor results on Sparkfun Thing

            My notes are in square brackets [ ]. Your nodeID & pin numbers could differ

Node 36 Version ESP32_nodes_n006B MQCON 5 BtnIO 0 Act 16         [Node 36 Btn on pin 0 (zero), ACTOR on pin 16]
Connecting to XXX
...
WiFi connected
IP address: 192.168.10.113
Connect to MQTT broker...connected

topic home/esp_gw/nb/node36/dev99 value:NODE 36 WAKEUP: ESP_36

topic home/esp_gw/nb/node36/dev02 value:-40
topic home/esp_gw/nb/node36/dev10 value:192.168.10.113
topic home/esp_gw/nb/node36/dev40 value:up                        [initial button state]
topic home/esp_gw/nb/node36/dev16 value:ON                 [ACTOR/LED (device 16) turned ON ...
topic home/esp_gw/nb/node36/dev40 value:dwn                     as button is pushed down]
topic home/esp_gw/nb/node36/dev40 value:up                    [button released to up]
topic home/esp_gw/nb/node36/dev16 value:OFF                    [ACTOR/LED turned OFF ...
topic home/esp_gw/nb/node36/dev40 value:dwn                        [as button is toggled down ...

topic home/esp_gw/nb/node36/dev40 value:up                                      & up]

            Next, Create Node36 Channel for Device 16 (ACTOR)

[papa]

        Adapting BUTTONIO to HiLetgo OLED ESP32 Board, etc.

As with Sparkfun ESP32 Thing prepare an LED with 100 ohm resistor. Connect the resistor lead to the board's pin 26 & the plain wire lead to a board GND. As here, connect a cabled push button to pin 2 & a GND.

        Node customizing on HiLetgo OLED ESP32 Board:
Deactivate (//) all customizing #defines from before (esp. BUTTON). Customize thus:
                Activate (no //) & match:
#define MQCON 12         #define BUTTONIO         #define BTN 2

        #define ACTOR                 #define ACT1 26

Pressing the push button should toggle the LED on & off.

        --------------------------------------------

        BUTTONIO Serial Monitor results on HiLetgo OLED ESP32 Board:

Same as for Sparkfun Thing above, except MQCON 12, Btn 2, Act 26, & different IP.

                BUTTONIO on Other ESP32 Boards

Adapt based on the above approaches to Sparkfun ESP32 Thing & HiLetgo OLED ESP32 Board. Also see about usable ESP32 pins in this post. Avoid trying to assign the ACTOR pin (output) to ESP32 input only pins (34-36. 39).

            Next, Create Node36 Channel for Device 16 (ACTOR)

[papa]

        Configure a Switch Type of Channel

                        This post & the next one apply to BUTTONIO on all boards.

If you built & configured Node36 with the BUTTONIO option above, it publishes the (on/off) status of the ACTOR (node device 16). OpenHAB can also command the ACTOR to toggle On or Off.

            Create Node36 Channel for Device 16 (ACTOR)  (Your node ID may differ.)

Logged in to your openHAB configuration, go to localhost:8080/settings/things/

In the listed Things, click Node36. Then click the [channels tab] near the top.

Near the bottom, click Add Channel.

        In the Add Channel Window, fill the fields with configs:

Channel identifier Node36Channel16
    ^^ arbitrary ? as long as we match it in a linked Item (see below)

Label Node36_Switch
    ^^ arbitrary ?, make it useful for yourself, but not too long

Channel type On/Off Switch
   ^^ choose type compatible with the device/channel data type

MQTT State Topic home/esp_gw/nb/node36/dev16
MQTT Command Topic home/esp_gw/sb/node36/dev16     << Note slight, but key difference in this topic.

        Click [Create] to save your configs

            Next: Create Item to Link to Node36's Channel 16

[papa]

        Create Item to Link to Node36's Channel 16

In an .items file, create an item entry based on the following. However, replace my channel UID with your channel UID determining it like you did in this post above.

Switch Act_Node36 "Node36switch" { channel="mqtt:topic:c08f02ca8d:3f938be488:Node36Channel16" }

Refresh the openHAB dashboard & the channel should link to the just created Item.

To display on HABPanel, use a Switch widget.

     The HABPanel switch tile should report the state of the ACTOR pin (clicks of the push button changes the state). Also clicking the HABPanel tile should toggle the state of the ACTOR pin & LED on the ESP32 node.

Nodes can have other devices/channels/functions which can be linked to openHAB via configurations similar to those just above in this thread.

        Next: ...