Cayenne Documentation


#1

myDevices Cayenne Online Dashboard Documentation

NOTE: This guide is a Work in Progress. We are constantly adding content and making improvements to it. Please share any feedback and suggestions on how we can make it better. We’re listening.

Introduction
This guide will help you to understand how to get started using Cayenne and give you the most comprehensive overview of all the features.

How Cayenne Works
Cayenne is the first of its kind drag and drop IoT project builder that empowers developers to quickly create and host their connected device projects. Cayenne was designed for the Internet of Things. It can control hardware remotely, it can display sensor data, it can store data, analyze and do many other cool things.

There are several major components in the platform:

  • Cayenne App – setup and control your IoT projects with drag and drop widgets from an app.
  • Cayenne Online Dashboard – Use a browser to setup and control your IoT projects.
  • Cayenne Cloud- responsible for processing and storage of device, user and sensor data for commands, actions, triggers and alerts.
  • Cayenne Agent – enables communication with the server, agent and hardware for implementing incoming and outgoing commands, actions, triggers and alerts.

Every time you press a button from the Cayenne app or online dashboard, it travels to the Cayenne Cloud where it’s processed and finds its way to your hardware. It works the same in the opposite direction. You can use the Cayenne mobile app or online dashboard, it’s up to you. Any changes you make to hardware from the mobile app are reflected when viewing the online dashboard and vice versa.

Features:

  • Connection using Ethernet, Wi-Fi and cellular (mobile app only)
  • Discover and setup Raspberry Pis on a network (Ethernet or Wi-Fi only)
  • Customizable dashboard with drag and drop widgets
  • Remotely access, reboot and shutdown a Pi
  • Add and control sensors, actuators and extensions connected to Raspberry Pis
  • Configure triggers for Pis, sensors and actuators
  • Setup and receive threshold alerts via email and text messages
  • Monitor device and sensor history data
  • Remotely test and and configure hardware using GPIO
  • Coming soon! Setup reoccurring actions and commands

Getting Started

This guide will help you get started using Cayenne in minutes. We will quickly cover the
following:

  • Creating your account

  • Installing and setting up Cayenne using a terminal

  • Configuring your first sensor (Temperature)

  • Configure your first actuator (LED Switch)

  • Setting up a trigger

Preparing your Raspberry Pi

  1. Power on your Raspberry Pi. Connect the power adapter to your Raspberry Pi.
  2. Connect the Pi to the Internet. Connect your Raspberry Pi to the Internet using an Ethernet cable. Or, if you have a Wi-Fi dongle setup already this works too.
  3. Make sure the Raspbian operating system is installed. Cayenne works with Wheezyand Jessy OS versions of Raspbian. Please make sure on of these is pre-installed. If you need to install the Raspbian operating system, click here.

Note: You do not need to make any configuration changes to the Pi device. Cayenne automatically handles setting up and configuring your Pi for use. However, it is recommended that you expand the filesystem on the flash card if necessary. Please refer to raspi-config if you need additional information on performing this step.

Creating your account
To use the online dashboard, you must first sign up for a free account.

To begin creating your account, visit the Cayenne Sign Up page.
From the Sign Up page, enter your Name, Email and create a Password.

Your account is now created. You can now proceed with installing Cayenne onto your Raspberry Pi devices.

After verifying your Raspberry Pi is powered on and connected to the Internet, click Next to begin the installation process.

Installing and setting up Cayenne using a terminal

Before you can manage your Raspberry Pi device using the online dashboard, you must install Cayenne onto the device. The instructions for installing Cayenne onto your device are displayed on screen.

Follow the on screen instructions to start the installation process. If you need additional help on this step, refer to the Video Tutorial.

As soon as the installation process starts, the Installing screen automatically appears. From here you can check on the installation process as it completes.

Cayenne installs on your Raspberry Pi in 4 steps:
Step 1: Installing libraries
Step 2: Installing agent
Step 3: Installing software
Step 4: Installing drivers
This may take up to 10 minutes. Please be patient.

As soon as the installation process completes, the online dashboard will automatically appear. Your Raspberry Pi is now ready to use!

Using drag and drop dashboard to control everything
After installing Cayenne, your Pi automatically shows up in the Cayenne drag and drop, customizable dashboard. With Cayenne everything is a widget so you can change the look and move things around for the look that works for you.

Things you can do include:

  • View CPU, RAM and storage usage.
  • Remote access, restart and shutdown your Pi.
  • Configure hardware using GPIO controls.
  • Configure Raspberry Pi settings
  • Customize widget type and look
  • Add devices such as sensors, actuators (e.g. lights, motors) and extensions.
  • Configure triggers for Pis, sensors and actuators
  • Coming soon! Schedule actions and commands

Configuring your first sensor

A couple notes before you get started:

  1. Make sure Raspberry Pi is powered off when connecting wires.
  2. When using a GPIO ribbon cable, make sure the power wire (it’s a different color than the others) is connected to the corner of your Raspberry Pi and the top of your Pi cobbler.
  3. The provided diagram is just an example of how to connect the sensor. There are many ways to connect sensors and extensions, so try what works best for you!
  4. Some full-size breadboards (used in diagrams below) have a powerline that is separated in the middle. If this is the case, be sure your sensors are connected on the same half of the breadboard as your Pi Cobbler.

Connecting a temperature sensor

For the purposes of this guide, we will use a BMP180 which is a Barometric Pressure/Temperature sensor.

Step 1: Connect the 3 volt power from your Pi Cobbler to the power line on your breadboard.

Step 2: Connect BMP180 VIN pin to the power line on your breadboard.

Step 3: Connect the ground pin from your Pi Cobbler to the ground line on your breadboard.

Step 4: Connect BMP180 GND pin to the ground line on your breadboard.

Step 5: Connect SCL pin from BMP180 to SCL pin on Pi Cobbler

Step 6: Connect SDA pin from BMP180 to SDA pin on Pi Cobbler

Step 7: Double check wiring, power Pi back on, and add the BMP180 sensor to your dashboard!

Using the online dashboard to add your sensor

Once your temperature sensor is wired up and connected to your Raspberry Pi, you can add it as a widget in Cayenne. Let’s add the BMP180 sensor now.

From the online dashboard, locate the Add new menu and select the Device entry.

On the Add Device screen you will see categories containing various sensors and devices that can be added. Click on the Temperature category in the list device types shown under Sensors.

After selecting Temperature, a list of temperature sensors will appear. Find the BMP180 sensor and click on it.

In order to add our new sensor widget to the dashboard, we will need to fill in a few details first.

Name: Enter “Temperature” for the name of our new widget.

Widget: Select the Value Display widget from the list of widget display types.

Icon: Select the Thermometer icon from the list of icons.
Altitude: Enter the current altitude where the device is.

Click Add Sensor to complete adding your temperature sensor widget. You will then be returned to the Dashboard where you will see your new temperature sensor added.

Using the Dashboard to control your actuator

Once your temperature widget has been added to the dashboard, Cayenne will begin monitoring your sensor. You can check the current status of your sensor at any time by visiting the dashboard.

The Value Display widget we chose when setting up our dashboard allows us to see the latest temperature value directly on the dashboard. Cayenne will constantly update this value as new sensor data arrives.

Let’s try it out! Open the dashboard so that the Temperature sensor is displaying and then** hold your hand on the BMP180 sensor**. The temperature value updates as soon as a change in temperature is received.

Configuring your First Actuator

A couple notes before you get started:

  1. Make sure Raspberry Pi is powered off when connecting wires.
  2. When using a GPIO ribbon cable, make sure the power wire (it’s a different color than the others) is connected to the corner of your Raspberry Pi and the top of your Pi cobbler.
  3. The provided diagram is just an example of how to connect the sensor. There are many ways to connect sensors and extensions, so try what works best for you!
  4. Some full-size breadboards (used in diagrams below) have a powerline that is separated in the middle. If this is the case, be sure your sensors are connected on the same half of the breadboard as your Pi Cobbler.

Connecting the actuator
For the purposes of this guide, we will use an LED light so that we can control it using the Raspberry Pi as a Light Switch to directly control our light.

Step 1: Connect the LED positive wire (the longer of the two wires) from resistor to a GPIO pin. In this example, GPIO 17.

Step 2: Connect the LED ground wire (the shorter of the two wires) to the GND pin from the Pi Cobbler.

Using the online dashboard to add your actuator
Once your LED is wired up and connect to your Raspberry Pi, you can add it to the Cayenne dashboard. Let’s add a Light Switch to control our light.

From the online dashboard, locate the Add new menu and select the Device entry.

On the Add Device screen you will see categories containing various sensors and devices that can be added. The switch that we want to add is located in the Actuators category.

Since we want to add a light switch, locate the Light tile and click on it to continue.

From the list of Light devices that appears, find and click on the Light Switch tile.

In order to add our new light switch widget to the dashboard, we will need to fill in a few details first.

Name: Enter “Light Switch” for the name of our new widget.

Icon: Select the Light icon from the list of icons.

GPIO: Our LED is connected directly to the Raspberry Pi, so make sure the Integrated GPIO is selected in the GPIO list.

Channel: When setting up our LED we wired the light to GPIO 17. Select 17 in the list of channels

Invert Logic: We want the light to start off and then turn on as we activate the button, so make sure that the Invert Logic is set to No.

Click Add Sensor to complete adding your switch. You will then be returned to the Dashboard where you will see your new switch added.

Using the Dashboard to control your actuator

Now that our light switch has been configured and added to the Dashboard, we can use the switch to control our light.

Because we created our light switch as a Button, we can use it to directly toggle the state of our light.

Click on the tile for the switch to turn the light on.

Your switch will now be toggled to On and the LED will turn off. Note how the button icon indicates the updated status the output.

You can toggle switch back Off by clicking the tile again. The button icon updates to indicate the output is once again off.

Setting up your first Trigger

Using the Triggers & Alerts feature, you can easily create triggered actions on and between your Pis, sensors and actuators based upon the state your devices. Turn on the lights when someone comes home, or open the blinds when the sun comes up. Cayenne makes creating such events easy by guiding you through this process.

Let’s create our first trigger. We’ll create a trigger to turn on our light when the temperature reaches a certain value.

  1. To begin creating a Trigger, open the up the feature by selecting Alerts & Triggers in the navigation menu.

  1. Click the New Trigger button to start creating a new trigger.

  1. The Create Trigger screen appears.

From here, you can fill in all the details required for creation of your trigger. When creating a new trigger, the empty screen serves as an overview of the creation process. To make this process easy, you will be guided through trigger creation that is easy to follow and select the devices and actions that you want.

Example: IF my device senses something, THEN do something in response.

  1. Let’s begin by giving our trigger a name. Enter “Temperature High, Turn on Light” into the Trigger Name field.

  1. We’re going to trigger when our temperature sensor does something. The Temperature sensor is located on our RaspberryPi device, so drag & drop the RaspberryPi device into the IF statement.

  1. After selecting the Temperature sensor, we can choose whether we want to trigger an action if temperature is above or below a certain value. We want to react to the temperature being high, so we select the Temperature from the list and select Temperature Above in the options presented.

  1. We want to take action once the temperature is high by turning on our light. Out Light is also located on the RaspberryPi device, so drag & drop that device into the THEN statement area.

  1. We can now choose an action to take on RaspberryPi. Since we want to turn on the light, select LightSwitch from the actions list and then choose On from the list of options available.

  1. We’re done! Click Save Trigger to complete our trigger and return to the Triggers list where our new trigger is shown.

  1. Cayenne will automatically synchronize the trigger with the Pi and will now start monitoring the temperature sensor and when it reaches the correct temperature your trigger will automatically run.

Problems installing Cayenne directly on Pi
#2

#3

#4

This guide seems to jump from setting up the BMP180 to a light switch. Am I missing something?


#5

Welcome!

The light switch (which is really just an LED connected to the Pi) was just used as an example. You could just as well setup a notification to send a text message or email if you don’t actually have an LED connected to your Pi yet.

-B


#6

Thanks. I understand that part. It seems the setup of the BMP180 was never completed in the guide. Just after step 7, the guide says “Let’s add the BMP180 sensor now.” but goes right into the light switch.


#7

I’ve read through several pages of welcome documentation but haven’t yet found out where to get the project breadboard and temp sensor, and what the heck is a “loT”?


#8

Yikes! I see now, you’re totally right. We’ll get this fixed right away. Thanks for letting us know.

@bmeriwether


#9

We don’t actually sell the hardware. You can purchase the hardware from a variety of distributors, such as https://www.adafruit.com/products/1603. We’ll be releasing tutorials for all connected hardware in near future as well.

IoT stands for the Internet of Things. Read all about it here https://en.wikipedia.org/wiki/Internet_of_Things. In a nutshell, Cayenne makes these IoT projects easy for anyone to do :slightly_smiling:

Let me know of further questions. You can view some good video examples here too:

Cheers,

-B


#10

Thanks bestes, the link to Adafruit was helpful. You might want to add a parts list to your projects so that it’s easy to get the right items and avoid frustration. It’s been about 40 years since I last used a bread board. Raspberry Pi;s are WAY fun as media machines and Linux systems. I’d like to try some home automation with one as well.

Thanks,
Joe


#11

Updated this doc post with correct pics. Let me know if you notice anything else.


#12

Thanks! Much better!


#13

Cool. We’ll post a better organized PDF doc of the above to our website as well when that section goes live.

-B


#14

Is there anyway to access via normal http and not https.
Our net nanny rips apart https and so we have certificate errors for most thing (e.g. most of google).
I’m wanting to test this with our Pi’s at our School (UK) and hopefully get the kids involved and interested in this style of IoT.

But for testing going through the hoops of getting any new and underdevelopment site added to the open wifi list may not be worth it.


#15

Sorry for late reply here. I think you’d need to open up the wifi. There is not way to access via http right now.

-B


#16

Had a chat about this with IT but given it a project in development and unknown at this stage, bypassing the netnanny and it’s snooping in secure server access isn’t going to be possible on the open WiFi. (we can’t even get most of google to be allowed to bypass it)

Which has stopped the idea in it’s track.
I tried to connect but it just wouldn’t.

so it’s just me playing at home now and the education environment idea has stopped.


#17

I’m moving this to the Archived section, because Cayenne now has a an extensive docs section. You can view it here.

-B


#18

Get an ESP8266 module and biff AT commands at it to make it do (just about) anything and a lot of other things besides :wink:

However for educational purposes I find the ESP and brilliant little wifi and it can be set up as an AP / Station / Scan wifi devices in the room / Join network and get and post data. It runs off 3xAA NiMH batteries and just a few jumpers to your weapon of choice Pi ? Dwino / Picaxe (in my case)

~ Andrew