Unofficial SmartThings + Arduino Documentation Collection

Hello, I’ve been designing and building some Arduino based Things and the lack of centralized documentation on the subject has been a bit frustrating. I finally figured out how to do a few things and this post is my attempt to centralize all the information I picked out of the documentation and forums.

I am assuming that you have a decent knowledge of Arduino. If not, go to http://learn.adafruit.com/category/learn-arduino for an excellent guide.

Installing the SmartThings library and initial configuration
https://support.smartthings.com/hc/en-us/articles/200901320, documentation is quite helpful with this. It will cover what libraries to download, how to pair the shield, changing your device type (What the SmartThings hub recognizes your Arduino device as), along with some examples and sample code.

Official Documentation
http://docs.smartthings.com/en/latest/smartapp-developers-guide/example-bon-voyage.html
Pretty high level, but still a good read.

http://graph.api.smartthings.com/ide/documentation
Kind of confusion, I break down working with Arduino in later links.

Sending data from your Arduino to the SmartThings Cloud
The above link (SmartThings + Arduino) contains example code! More specifically, it contains a link to an on/off example https://gist.github.com/aurman/6546221. This is a good place to get started, and I will now break down said code.

Code to put into the top of your C file

#include <SoftwareSerial.h>   //TODO need to set due to some weird wire language linker, should we absorb this whole library into smartthings

#include <SmartThings.h>

//Is this important for my application?

#define PIN_THING_RX    3
#define PIN_THING_TX    2

SmartThingsCallout_t messageCallout;    // call out function forward decalaration
SmartThings smartthing(PIN_THING_RX, PIN_THING_TX, messageCallout);  // constructor

What does this stuff do? I have no idea, but the example file has it so you should probably throw it in your code too! :slight_smile:

Code to put in your void loop()

void loop()
{

 smarthings.run()

 Put the rest of your loop code here

}

Okay, now how do I send stuff to the CLOUD!!

example: smartthing.send(your message here!);

smartthing.send("release");

Amazing! Now how do I make the cloud read my message and act upon it?
Source code for built-in device types? explains and documents the SMART code that you need to read messages from your Arduino and act upon them.

Getting started with device types? (scroll down to Danny Kleinman’s post and it will explain what the above link says but it is a bit more clear).

Sending data from SmartThings Cloud to your Ardunio

Writing C code to listen to data from the Cloud
First, read the Sending Data from your Arduino section about to understand the basics. (and read the on/off example!)

The example code contains this function:

void messageCallout(String message)
{
  // if debug is enabled print out the received message
  if (isDebugEnabled)
  {
    Serial.print("Received message: '");
    Serial.print(message);
    Serial.println("' ");
  }
 
  // if message contents equals to 'on' then call on() function
  // else if message contents equals to 'off' then call off() function
  if (message.equals("on"))
  {
    on();
  }
  else if (message.equals("off"))
  {
    off();
  }
  else if (message.equals("hello"))
  {
    hello();
  }
}

As you can see, if (message.equals(“on”)) will trigger is the Arduino receives an “on” command from the SmartThings cloud!

How do you pass a string (as opposed to always saying on/off/ect) from the cloud to Arduino? I have no idea, figure it out.

How can I press the button (aka Tile) and have it send data to my Arduino??
Go to Getting started with the SmartThings Arduino shield and scroll down to Juan Risso’s reply. He explains how to use the SmartThings IDE to write SMART (aka Groovy?) code that will let you use tiles to send commands to your arduino!

Now, let me explain this more in depth.

This is the example On/Off Button Tile Code

/**
 *  On/Off Button Tile
 *
 *  Author: SmartThings
 *
 *  Date: 2013-05-01
 */
metadata {
	// simulator metadata
	simulator {
	}

	// UI tile definitions
	tiles {
		standardTile("button", "device.switch", width: 2, height: 2, canChangeIcon: true) {
			state "off", label: 'Off', action: "switch.on", icon: "st.switches.switch.off", backgroundColor: "#ffffff", nextState: "on"
			state "on", label: 'On', action: "switch.off", icon: "st.switches.switch.on", backgroundColor: "#79b821", nextState: "off"
		}
		main "button"
		details "button"
	}
}

def parse(String description) {
}

def on() {
	sendEvent(name: "switch", value: "on")
}

def off() {
	sendEvent(name: "switch", value: "off")
}


state "off", label: 'Off', action: "switch.on", icon: "st.switches.switch.off", backgroundColor: "#ffffff", nextState: "on"

will launch a action named “switch.on”, in this case it will run the function def on(). This def on() function will then do whatever you tell it to! More specifically, if you want it to send data to the arduino, try:

'zigbee.smartShield(text: "e").format()'

This will send the letter “e” to the Arduino!

How can I change my tile icon??
The great Dianoga made wrote http://scripts.3dgo.net/smartthings/icons/, a page with all the icons and their name!

His original forum post is Tiles/icons path and file names.

The Elusive ThingModule!

6 Likes

Bookmark’d.

Very cool. Thank you.

One thing you might want to add. If you wan to use the ThingShield on a Leonardo board, you cannot use pins 2/3 for the ThingShield. The issue is the Leonardo does not support SoftwareSerial on those pins… specifically, what that means in pin 3 cannot be used as a serial RX pin. Here’s my workaround (credit to @urman at ST):

Jumper pin 10 to pin 3 on the shield, then do this in your code:

#define PIN_THING_RX    10
#define PIN_THING_TX    2

Then it will work.

2 Likes

Hi Steve,

I didn’t know about that, I’ve only been using Unos. Apart from the TX and RX pins, what other others do you need to connect from your Arduino to the ThingShield? I imagine Vcc and ground as well.

Cheers,
Jordan

Updated links for Arduino stuff:

https://support.smartthings.com/hc/en-us/articles/200901320

1 Like

I am getting the following when attempting to click on the link

oops.

You’re not authorized to access this page.

Which link @chaospup ?

https://support.smartthings.com/hc/en-us/articles/200901320

Is it ok to put a delay at the end of the loop? I’m just wondering if that will interfere smartthing.run(). I’m thinking of putting an hour delay on it.