Enabling the Community with SmartThings Technology

September 2012, Version 1.0.0 by the SmartThings Engineering Team

What are SmartThings?

Remember the Jetsons?

SmartThings are where the physical meets the virtual. SmartThings are devices, from door locks to hot-tub controllers to fleets of robotic tree-trimming helicopters (watch out!). SmartThings automatically connect to the SmartThings platform to allow for both monitoring and control. Once they are connected, SmartApps can be applied to automate your SmartThings!

Any “thing” that you can imagine that can be controlled, monitored/measured, integrated, or automated can be a SmartThing. They can be useful, mission-critical, or just lots of fun — you decide.

SmartThings are integrated into the SmartThings Platform. They communicate with our SmartThings Hub and Cloud. Once a device is a “SmartThing”, it can be controlled and managed through SmartApps to integrate it with other devices and automate its behavior in truly amazing ways.

Our Vision

We think that the world can be much smarter – monitorable, controllable, automatable, and more fun. Our vision is that SmartThings can become the key enabling platform, worldwide, that brings the “physical graph” online.  Because it is just a platform, however, it requires a community of developers and makers to realize the potential of this vision.  And the crazy break-through innovations of the future are going to come from that community!

The SmartThings Maker Community will include everyone from maker-hobbyists to manufacturers that want to offer SmartThings compatible devices.

We want to enable virtually anyone with the maker skill-set to build or prototype a device, integrate it with the SmartThings Platform (our SmartHub and the SmartThings Cloud), and make that device into a SmartThing!

We want to make this as friction-free as it can possibly be, and we are going to provide products, tools, services, and a community that will make this a reality.  Makers will be able to rapidly innovate using our technology to solve real-world problems, and through the community, find the resources necessary to bring those solutions to market quickly.

We think SmartThings and SmartApps are the future, and we want you to be part of it!

Concepts and Terminology

When we talk about building Smart Things – or SmartThings, it helps if you have some concepts and terminology straight. Not all of these features will be available at the initial launch. We may even change some of the names.  But just reading through the definitions will give you some insight into the direction we are headed.

Things – Anything.  Just a thing.  A pencil.  A coffee cup.  A pool filter, etc.

Devices – A thing that supports specific capabilities and attributes.  All devices are things.  Not all things are devices.  For example, a pencil has the capability to write, erase, or be chewed on (capabilities).  It also has attributes like how long it is, how much eraser is left, how many bite marks are on the outside.

Capabilities – A description of the actions that can be performed by a device.

Attributes – A collection of data values that collectively tell us the current state of the device.

SmartThings – A device that is integrated with the SmartThings platform.  Why didn’t we call it a SmartDevice?  Because the domain name was better this way. So there.

Commands – An instruction to a device to perform one of its capabilities.

Events – A report of a change in or update to one of a device’s attributes.

Standard Events – Events related to standard device types, or the SmartThings Cloud itself.

Custom Events – Custom events generated by SmartApps developers, SmartService developers, or SmartDriver developers.

ThingModule – A Land Grid Array (LGA) module that can be mounted to a Printed Circuit Board (PCB) that has all of the required hardware and firmware to turn a device into a SmartThing.

ThingShield – A ThingModule integrated into an Arduino shield to make it easy to build SmartThings prototypes using Arduino.

Device Type Bindings - Meta-data instructions that define the capabilities and attributes of a specific type of device.

Dynamic Bindings – Device Type Bindings that can be applied to a ThingModule dynamically to define the capabilities and attributes of the device and allow control of the device through the ThingModule.

SmartDriver – A virtual device driver in the Cloud that sends commands to a SmartThing and generates events on behalf of the SmartThing based on reported attribute changes.

SmartApp – An Internet-of-Things application that does stuff with one or more SmartThings.  In its simplest form, a SmartApp is a collection of Event Handlers that are automatically executed when a specific Event (from a device, an external event, etc) occurs.

SmartService – A service running in the SmartThings Cloud that provides services to SmartApps.  For example, the Twilio SmartThings service provides two-way integration between a SmartApp and Twilio.

Building SmartThings

As we are just getting started, at initial launch makers and manufacturers have two primary choices for building devices (a.k.a. SmartThings) that are integrated with the SmartThings Platform.

  • Use the SmartThings ThingModule and integrate it directly into your product
  • Prototype or build your device using the SmartThings Arduino Shield

What is the ThingModule?

The SmartThings ThingModule is a Land Grid Array (LGA) module that can be mounted to your own PCB.  It has all of the required hardware and firmware to help you turn your device into a SmartThing.  On the ThingModule is a microprocessor, ZigBee (802.15.4) radio, integrated antenna, and firmware that will allow you to integrate the ThingModule easily into your device.

For device manufacturers, the ThingModule is going to be the standard way to integrate with the SmartThings Platform and is designed to support large scale manufacturing.  It has been designed to be extremely inexpensive (less than $10 per device), powerful (built-in antenna, cloud connectivity firmware, etc.), and pre-certified for fast track certification of your finished SmartThing.

We’ve also kept it small (0.85″ x 1.00″) so that it can easily integrate with your existing devices/applications.

The ThingModule provides the following capabilities:

  • Leading edge Zigbee radio, integrated SmartThings cloud communications stack, and on-chip antenna, providing turnkey connectivity between your device and the SmartThings platform
  • Automated Hub Connectivity Management (Network Join, connect, re-connect, status reporting, etc)
  • A Serial Port with a Command Line Interface (CLI) and command language to configure the ThingModule, send status information to the SmartThings Cloud and receive commands from the SmartThings Cloud.
  • 15 Available GPIO pins that can be dynamically bound to virtual commands and virtual device attributes (using Commands), allowing your device to accept commands and report status without the need for custom firmware.
  • Automated device health-check and status reporting based on preferences.
  • 1 GPIO pin that supports the ability to implement a manual control button if needed
  • Command access through the ZigBee network or from the serial port

And here are some additional technical specifications on the ThingModule:

  • 0.85″ x 1.00″ LGA (land-grid array) module
  • Integrated PCB antenna
  • Supply voltage range of 2.1V – 3.6V
  • Integrated 24 MHz oscillator
  • Ember EM357 ZigBee SoC with 192 kB of FLASH and 12 kB of RAM
  • 21 I/O pins broken out to module pads, including serial UART, SPI, TWI, JTAG, packet trace (JTAG and packet trace require an Ember development kit)

Working with the ThingModule

The SmartThings ThingModule is a Land Grid Array (LGA) module that can be mounted to your own PCB.  It has all of the required hardware and firmware to help you turn your device into a SmartThing.  On the ThingModule is a microprocessor, ZigBee (802.15.4) radio, integrated antenna, and firmware that will allow you to integrate the ThingModule easily into your device.

We’re making the integration with the ThingModule as easy and friction-free as we can possible make it.

There are two primary usage scenarios with the ThingModule.

  • Connectivity Mode – Using the ThingModule to Connect and Communicate to the SmartThings Platform from an existing Microcontroller
  • Custom GPIO Mode – Using the ThingModule as the Primary Microcontroller for your device and to communicate to the SmartThings Platform

Each of these modes or capabilities is described below.

Connectivity Mode

Connectivity mode is best suited for applications where you already have an existing microcontroller in your device, and you simply want to interface that existing device with the SmartThings platform.  In connectivity mode, think of the ThingModule as just a gateway to the SmartHub.

Connectivity mode makes use of a Serial port on the ThingModule and supports a Command-Line Interface (CLI) to send status updates from your microcontroller and to receive commands (originating from the SmartThings Cloud) from the SmartHub.

Custom GPIO Mode

Custom GPIO Mode is used when you want the ThingModule to be more than a connection to the SmartHub.  This mode allows you to use the ThingModule’s meta-programming capability to establish Dynamic Device Bindings to any of the ThingModule’s 19 GPIO pins.

These bindings allow you to describe how you want to use these pins in order to expose device capabilities and attributes to the SmartThings Cloud.

The bindings can be established by defining a custom device type in the SmartThings Cloud maker account, or by sending binding commands to the ThingModule over the serial port.

In addition to the dynamic bindings, you can also use meta-programming to set event reporting preferences on the ThingModule to tell us under what conditions it should report status (Events) to the SmartThings Cloud.

Connectivity + Custom GPIO Mode

While we talk about them as “modes”, these modes simply represent capabilities of the device and you can use both at the same time, using dynamic GPIO device bindings while also using the serial interface to communicate with the SmartThings platform.  Pretty cool huh?

What is the SmartThings Arduino Shield?

The SmartThings Shield is an add-on module for the popular Arduino (http://en.wikipedia.org/wiki/Arduino) open-source electronics prototyping platform.

The shield makes our standard ThingModule easily accessible to the Arduino and includes an Arduino library that makes it very easy to integrate the ThingModule into your Arduino project.

The shield makes it easy to:

  • Wire sensors or other components to any of the 15 GPIO pins available on the ThingModule
  • Communicate to the SmartThings Platform using a serial interface
  • Establish dynamic device bindings for ThingModule capabilities and attributes
  • Read/write device attributes and issue commands
  • Set reporting preferences and command the ThingModule to report on-demand

And here are some additional technical specifications on the ThingShield:

  • Compatible with Arduino Uno, Duemilanove, Leonardo, and Mega1280/Mega2560
  • Communicates with ThingModule using hardware serial or software serial (switch selectable)
  • Uses 1 Arduino pin for general-purpose signalling to the ThingModule (D6)
  • Includes RGB LED and general-purpose push-button switch connected directly to the Thing Module
  • Prototyping area with +5V and +3.3V supply rails
  • Stacking headers for adding shields on top
  • Through-hole pads for soldering wires to connect to Thing Module I/O pins

Working with the SmartThings Arduino Shield

Just how easy is it to build a SmartThing using Arduino? As easy as 1-2-3.

  • Step 1 - Design & Prototype your device to use our SmartThings Arduino Shield and our Arduino library. We’ll provide some sample Arduino Sketches to help get you started. Most Arduino developers will likely want to
    use the CLI interface from the ThingModule,
    so that means that you’ll be receiving commands from the module and you’ll need
    to do something with them. Conversely you’ll need to report device status back to the ThingModule using a status command.
  • Step 2 - Define your new Custom Device
    Type to the SmartThings Cloud. This involves telling us about the capabilities and attributes of your device in our Maker Portal. Note that we are also working hard to ensure that you as a maker are in control of any intellectual property associated with the SmartThings that you are creating. From the capabilities and attributes of your devices to the SmartApps source code that you create to enable them, we want you to decide if and when you share that with the rest of us.
  • Step 3 - Plug it in, turn it on, watch it appear in our mobile app, give it a command, watch it do something cool! Of course your device will also be immediately accessible through our APIs as well, and you’ll even be able to control whether is shows up in the mobile app!

How We Build Our Own SmartThings

Our goal is to open-up the SmartThings Platform and technology stack to our Developer and Maker communities.

We don’t want to have special case situations for our own SmartThings or SmartApps if we can help it. We want to give the community all of the same power and capabilities that we have!

With the single exception of the presence tag, the initial set of SmartThings (even the hub) that we are manufacturing ourselves will use the ThingModule to integrate with the SmartThings platform.  Our own devices connect and communicate just like the SmartThings that we know are going to evolve out of our Maker Community!

An example of this is our open-close contact sensor shown here. You can see the ThingModule surface-mounted to the contact sensor PCB.

The SmartThings Maker Community

At a high level we envision two primary communities that will help us to drive the SmartThings vision and make it a reality.  The SmartApps developer community, and the SmartThings maker community.

Of course we expect Makers will also be writing SmartApps, but the Makers are the folks that like to get their hands dirty building devices and then turning them into SmartThings. Most SmartApps developers won’t know what an Arduino shield even is, so it will be the SmartThings maker community that makes all of the higher levels of innovation possible by connecting anything and everything to the SmartThings Platform for, you know, control, automation, and fun.

Who Will Participate?

We expect the Maker community will include members from home hobbyists to engineers at large manufacturers to student labs at Universities.  We expect makers from all over the world to participate too!

If you own a soldering iron, you should be a part of the SmartThings Maker community.

Benefits of Being a Part of the Community

When we say community, we mean it in the most collaborative and supportive way possible. We want to see a community of Makers that shares ideas, works together to solve problems, and accelerates the vision of an Internet of Connected Things.  Our own engineers and maker lab will be a big part of the community as well.

Together, we are going to make that vision a reality, and that means creating a community that not only collaborates to create new SmartThings, but that includes investors, manufacturers, and distributors that can work with makers to help bring their new SmartThings to market.

When is this Going to Happen?

We are working hard to get the SmartThings Platform Version 1.0 out the door and into the hands of makers, developers, and end-users as quickly as possible.  But we aren’t going to wait for the official launch to start enabling the Maker community.  We’re going to get the community website up and running in advance so that ideas and innovation can start to happen now!  Stay tuned, but we promise you won’t have to wait long!