Kevin Newhouse

API Button: Custom Built, Low-Cost IoT

IoT Background

Okay, here’s a relatively new world for me.  One of my professional goals this year is to get more into the IoT space, and I recently built an API to control my basement’s lights and music during hockey games.  Although triggering the API with a Xamarin app worked just fine, my real vision for this project was to be able to slap a large button to kick off the celebration (just like the famous Staples “Easy Button”).  I sought out to purchase a large WiFi push button that could send an HTTP request to a provided address.  I looked into all kinds of products, including Amazon Dash, bttn, and flic.  But nothing really seemed to suit my needs.  It looks like the closest I could find were products that interfaced with IFTTT.  I’m sure those are great, but I don’t need the overhead/latency involved with IFTTT.  So, onto what any good engineer would do in this situation – build the API Button myself.

API Button Materials List

Following a recommended guide, I prepared with a few low-cost accessories (just in case I broke or fried something – I really need to have more confidence in my initial abilities on hardware projects.  For the record, no electronic parts were hurt in the making of this project).  This included some push buttons, caps, female/female jumper wires, and an ESP8266 development board.  For those unfamiliar, ESP8266 is really an incredible device.  At a price point less than $10 on Amazon Prime, you get a board that can be flashed, run LUA scripts, handle GPIO hardware, and even connect to a wireless network.  I recommend getting the model linked above, because it comes with GPIO header pins and a Micro USB port already connected.

Software Setup

I first set up the board and ensured everything was running by installing this LUA script.  It’s pretty simple – wire up the button via the board’s GPIO pins, upload the script via LuaLauncher, and reboot the board.  Since I called the script init.lua, it automatically loads on boot (which, by the way, is pretty damn quick).  Press the button once, the onboard LED turns on.  Press it again, and the LED turns off.  Looks like our button input and script are working!

Calling our API

Next, just a little bit of tweaking to that script.  Instead of toggling the onboard LED, we need to make the HTTP request.  A note to the critics out there: I don’t consider myself fluent in LUA, so my code probably doesn’t conform to best practices.  My goal here was to write functional code, not to become a LUA expert.

#include <esp8266httpclient.h>

-- Config
local goal_button_pin = 3

local pin = 4            --> GPIO2
local value = gpio.LOW

-- init GPIO pin properly
-- some hardware might not need the "gpio.PULLUP" part, mine does
gpio.mode(pin, gpio.INT, gpio.PULLUP)

-- Function calls API
function callApi ()
    http.get("http://<IP_ADDRESS>:<PORT>/api/goal",
        "apiKey: <API_KEY>\r\n",
        function(statusCode, data)
            if (statusCode < 0) then
                print("HTTP request failed")
            else
                print(code, data)
            end
        end)
end

-- define a callback function named "goalBtn", short for "pin callback"
function goalBtn()
    print("Pressed 1")
    callApi()
end

gpio.mode(pin, gpio.OUTPUT)
gpio.write(pin, value)

-- register a button event
-- that means, what's registered here is executed upon button event "up"
gpio.trig(goal_button_pin, "up", goalBtn)

“That Was Easy!”

And there you go!  Now our API Button is working.  Now that we’ve got a basic solution, we can use something a little more useful than a tiny button.  Again, I couldn’t get the Staples Easy Button out of my head.  Finally, I stumbled upon these large dome push buttons.  Wiring is extremely similar – I just pulled off one of the female jumpers on my wire, stripped a little extra insulation, and wrapped it around the terminals.  Ensure our connections are solid with some solder and throw a little heat shrink tubing on the whole thing for a nice clean look.  You can also wire up the API Button’s LED to a power source, however I chose not to.

Project Box

But of course, I can’t deal with all of those loose wires.  I saw some suggestions online that involved buying a cheap plastic project box and taking a hacksaw to it, but I wanted something a little more hefty. Luckily, I’m getting pretty decent at woodworking, so I was able to create this box.  Note that if you’re going to do the same, I used a 15/16″ spade bit to drill the hole that the API Button’s base sits on.  A 1″ bit probably would work, but I wanted a perfect fit.  And besides, what’s a project without a trip to Harbor Freight?

After a good sanding and some stain, the finished product:

And a video of it in action!

 

Conclusion

Remember, this project is meant to be a barebones starting point for those getting into IoT.  Since all we’re doing here is performing an HTTP GET call, we can apply this concept to a number of platforms (Microsoft Flow, IFTTT, Custom APIs etc.) to trigger just about any task.

Next, I’ll be looking into some more uses for a button like this – specifically something a little more Microsoft-y.  If there aren’t already some good resources for my approach, you’ll be sure to see another post extending the subject.