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.

This guide will help you to understand how to get started using Cayenne and give you the most comprehensive overview of all the features. If you want to jump straight into playing with Cayenne, check out Getting Started.

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

Install Cayenne directly onto Raspberry Pi using the online dashboard.

You can use the Getting Started guide to help you get started using Cayenne in minutes. We’ve prepared a guide for getting started with the Cayenne mobile app as well as the Online Dashboard. Both guides will cover the same information, so select the appropriate guide depending upon whether you want to start with the mobile app or the online experience.

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

• Installing the mobile app onto your device
• Creating your account
• Discovering and setting up Cayenne using the mobile app
• Configuring your first sensor (Temperature)
• Configure your first actuator (LED Switch)
• Setting up your first trigger

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 Wheezy and 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.

1. To begin, download and install the mobile app onto your device. After installing the app onto your device, open the app to begin the sign in process.

2. After opening the mobile app, you will be asked to create your account. Select the Create my free Account link to continue.

3. Begin by entering your name and then tap Next Step to continue.

4. Enter an Email address and a Password to be used to create your account. You may use these same credentials if you wish to use the online dashboard in the future.

5. Your account is now created. You can now proceed with using the mobile app to setup and configure your devices.

1. After creating your account, you will see the Discovery screen. Cayenne automatically discovers all the Pis located on the same network as your mobile device. To begin the discovery process, tap the Find Raspberry Pi’s button.

2. The discovery process will scan the network looking for Raspberry Pi devices. Any Pi devices located on the same network as your mobile device will be found.

3. After the discovery process completes, you will be shown a list of Raspberry Pi devices found. To control these Pi devices, tap to select them and then tap the Setup Button to setup and install Cayenne on your Raspberry Pi.

4. 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.

5. You will see confirmation shown when Cayenne is successfully installed. Your Pi device is now ready to be controlled using the mobile app.

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

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.

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!

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.

1. Using the mobile app, tap the + icon to go to the Add Device screen.

2. From the Add Device screen, tap on the Temperature category in the list device types shown under Sensors.

3. After selecting Temperature, a list of temperature sensors will appear. Find the BMP180 sensor and tap on it.
Pro Tip: If you know the exact part number or device name of the device you want to add, you can enter this information into the search field to quickly find it.

4. 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.

5. Tap Add Sensor and your new temperature sensor widget will be added to the dashboard. You will be returned to your dashboard and your new Temperature sensor will appear there.

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.

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.

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

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.

1. Using the mobile app, tap the + icon to go to the Add Device screen.

2. 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 Tap on the Actuators tile to continue.

3. Within the Actuators category, you’ll see a list of models for devices that can be added. Since we want to add a light switch, locate the Light tile and tap on it to continue.

4. From the list of Light devices that appears, find and tap on the Light Switch.

5. 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 tap the button, so make sure that the Invert Logic is set to No.

6. Tap Add Switch to complete adding your switch. You will then be returned to the Dashboard where you will see your new switch added.

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 Triggers in the nav bar.

2. Tap the + icon to start creating a new trigger.

3. 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.

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

5. We’re going to trigger when our temperature sensor does something, so tap the IF tile to start selecting our device.From the list of devices that appear, select our Temperature sensor since that’s what we want to monitor.

6. 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 Temperature Above from the list.

7. We want to take action once the temperature is high by turning on our light. Tap the THEN tile and select our Light Switch from the list of devices that appears.

8. After selecting our light switch, we’re shown a list of actions we can take on the light. We want to turn on the light, so select On from the list.

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

10. 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.

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

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 Wheezy and 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.

To use the Online Dashboard you must first sign up for a free account.

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

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

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

1. 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.

2. 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.

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

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

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.

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!

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.

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

2. From the Add Device screen, click on the Temperature category in the list device types shown under Sensors.

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

Pro Tip: If you know the exact part number or device name of the device you want to add, you can enter this information into the search field to quickly find it.

4. 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.

5. Click Add Sensor and your new temperature sensor widget will be added to the dashboard. You will be returned to your dashboard and your new Temperature sensor will appear there.

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.

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.

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

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.

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

2. 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.

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

4. 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.

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

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.

1. 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.

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

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.

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

3. 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 “Temp High, Turn on Light” into the Trigger Name field.

2. 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.

3. 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.

4. 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.

5. 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.

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

7. 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.