Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
499 lines (259 sloc) 32.5 KB

Getting Started

Create Cayenne Account

You can create an account from Mobile or online. Mobile is the easiest and fastest way, but instructions for online set up are below:

On the Sign Up page, enter your Name, Email and create a Password.


Sign up for Cayenne

Choose Device

Cayenne currently supports Raspberry Pi, Arduino and LoRa devices. Select the device you would like to get started with in your IoT project.


Choose device category

The next section covers getting started with a Raspberry Pi device.  If you’re using an Arduino device to get started, click here. If you’re using a LoRa device to get started, click here.

Raspberry Pi

Getting started in minutes!

  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 Jessie OS versions of Raspbian. Please make sure one of these is pre-installed to the sd card. 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.


Raspberry Pi

Installing Cayenne

Installing from the Mobile App

<iframe width="480" height="270" src="https://www.youtube.com/embed/J9zqvGWB5tM" frameborder="0" allowfullscreen></iframe>

Before you can manage your Raspberry Pi device using the mobile app, you must install the Cayenne app onto your mobile device. Installing and using the mobile app is the easiest way to get started with Cayenne. If you need additional help on this step, refer to the video tutorial above.

Visit the Mobile App download page to find the appropriate app store link for your device.

After installing the Cayenne app onto your mobile device, you will be guided through finding and installing Cayenne on all of your Raspberry Pi devices.

Installing from the Web

<iframe width="480" height="270" src="https://www.youtube.com/embed/Qx0IHv-UR-0" frameborder="0" allowfullscreen></iframe>

1. Before you can manage your Raspberry Pi device using the online dashboard, you must install Cayenne onto the device.

After verifying your Raspberry Pi is setup and powered on, you can continue with connecting your device to Cayenne.


Raspberry Pi Step 2

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

NOTE: The commands displayed on screen will be customized uniquely for the device being added and for your account. Do not share or re-use the installer downloaded from these commands - If you need to install additional devices, or reinstall onto this same device, you should follow the installation process again for each device.


Raspberry Pi Step 3

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.


Installing Cayenne

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


Cayenne First Experience

Sensors

Cayenne works with temperature, luminosity, pressure/distance, motion and generic sensors connected to your Raspberry Pi devices. View supported sensors

EXAMPLE: Let’s add a BMP180 temperature and pressure sensor to see how easy it is to get started.

Connect the BMP180 as shown here. View BMP180 hardware tutorial


Cayenne Step 4

Click Add New > Device / Widget.


Add New Device

  1. Select Sensors, Temperature, then BMP180.
  2. Click Add Sensor.


Add Sensor

Read your Sensor

The BMP180 temperature and pressure widgets are added to your dashboard.

Let’s try it out! Place your hand on the BMP180 sensor. The temperature value updates as soon as a change in temperature is received.

You can check the current status of your sensor at any time by visiting the dashboard.


Added Sensor

Actuators

Cayenne works with light, motor, valve, relay and generic actuators that are connected to your Raspberry Pi devices. View supported actuators

EXAMPLE: We will switch on an LED connected to your Raspberry Pi using Cayenne.

Connect an LED to Channel 23 as shown here. View LED tutorial


LED Step 2

Click Add New > Device / Widget.


Add New Device

  1. Select Actuators, then Light, then Light Switch.
  2. Enter “LED” in Name field.
  3. Choose channel 23.
  4. Click Add Actuator.


Light Switch

The LED widget has been added to your dashboard. Click the LED button in the dashboard to turn the LED on and off.


Light Switch to Dashboard

Extensions

You can add analog, digital and PWM extensions to your Raspberry Pi. This allows you to add more sensors and actuators to your Raspberry Pi. View supported extensions

Arduino

Get started in minutes!

<iframe width="480" height="270" src="https://www.youtube.com/embed/hmIGRrvevCA" frameborder="0" allowfullscreen></iframe>

Before you can manage your Arduino device using the online dashboard, you must setup your device and install the Cayenne Arduino Library onto the device.

Arduino Setup

Begin by verifying that your Arduino board and PC/Mac are correctly set up before continuing.


Step 2 Arduino

Connect the Arduino to the Internet

Make sure your Arduino is connected to the Internet. On most Arduino boards, you will need to connect an Ethernet or Wi-Fi shield in order to connect your board to the Internet. Verify that you have a shield supported by Cayenne installed and working.

Connect the Arduino to a PC/Mac

Power on your Arduino by connecting your Arduino with a USB cable (or FTDI connector if you’re using an Arduino pro). You should see the power LED lit on your board.

TIP: If you will have more than a couple of sensors attached to your Arduino, it may be a good idea to also supply power to the Arduino using the external power jack. This will ensure that after your board is programmed and running, it has sufficient power for all your connected devices.

Using Cayenne Arduino Library

The Cayenne Arduino Library is a collection of code, known as sketch files, that makes it easy for you to connect and send data to and from sensors, actuators and devices connected to Arduino boards. Cayenne sketch files can be combined with other sketch files for your IoT projects. In this section we will walk you through installing and configuring the Arduino IDE to use the library.

Installing Arduino IDE Software

To use the Cayenne Arduino Library, the Arduino IDE software should be installed. Go to https://www.arduino.cc/en/Main/Software to download and install the Arduino IDE software if you need it. Arduino IDE can be installed on Windows, Mac or Linux computers.

Add Cayenne Library to Arduino IDE

The Cayenne Library is a collection of code, known as sketch files, that makes it easy for you to connect and send data to and from sensors, actuators and devices connected to Arduino boards. Cayenne sketch files can be combined with other sketch files for your IoT projects.

The Cayenne Library is available directly from the Arduino IDE Libraries list. To install the library, select Sketch > Include library > Manage Libraries. The Library Manager dialog will appear. From here, search for the Cayenne library and install it.


arduino-ide-manage-libraries


arduino-ide-add-cayenne-lib-using-lib-manager

The Cayenne library has now been expanded in the libraries folder in your Arduino sketches directory. You can verify this by going to the Sketch > Include Library menu where you should now see the Cayenne library at the bottom of the drop-down menu under Contributed Libraries. The Cayenne library is now ready to be used in your project.


Cayenne Library Installed

Configure Arduino IDE

In order to successfully program your Arduino board, you will need to verify that the appropriate Board and Port are selected in the Arduino IDE.

First, verify that the correct Board is selected in the Tools > Board menu. Be sure to select the board type that you will be programming.


Arduino IDE board selection

Then, verify that you have the correct Port selected for communicating with your Arduino. Pick the correct port based upon how you are connecting your Arduino to your PC/Mac.


Arduino IDE port selection

Connect your Arduino

After setting up your PC/Mac computer with the Arduino IDE and the Cayenne Library, you are ready to install Cayenne onto your device. Continue to Step 3 of the Arduino installation, where you will connect your board with Cayenne.

On this screen, select the Arduino board that you are using from the list of supported boards. As you select your Arduino board, a list of connections appears below the board name. Select the connection type that you are using.


Arduino Step 3

Click on the Sketch button next to the connection you will be using and a popup will appear with the sketch file you will need when flashing your Arduino device. The sketch file will contain everything you need to connect your device to Cayenne, including your authentication token.


Arduino Step 3 Connection Example

Copy & paste the sketch file contents into Arduino IDE and select Sketch > Upload to upload the sketch file to your device.


Arduino IDE paste example sketch

As soon as your Arduino device comes online and connects to Cayenne, you will see your Arduino Board in the online dashboard.


Arduino 1st Experience

Congrats! You are all set! Now your hardware is connected to the Cayenne Cloud!

If you run into any troubles, see Troubleshooting for things to check.

Sensors

Cayenne works with any sensor that is connected to an Arduino. We’ve created sketch files for the various temperature, luminosity, pressure, proximity, motion and generic sensor models.

EXAMPLE: Let’s add temperature sensor TMP36 to see how easy it is.

Connect the TMP36 as shown here. View TMP36 hardware tutorial


Arduino TMP36 Step 3

Click Add New > Device / Widget.


Add New Device

  1. Choose Sensor > Temperature > TMP36.
  2. Choose Virtual from the I/O field.
  3. We will use Virtual Pin 1 for this example. Choose V1 from the Pin field.
  4. Click the Step 1: Sketch File button to view the sketch file.


Arduino Add Device TMP361

A popup will appear showing the TMP36 sketch file. Copy the sketch file contents to the clipboard and open Arduino IDE.


Arduino Add Device TMP361 Sketch File

Paste the TMP36 sketch file code into the Arduino IDE. After copying & pasting the example sketch files, you will want to double check that your authentication token is correct as well as update any pin assignments that appear in the sketch file. Read more about using sketch files

In this case, we are using the default Virtual Pin 1 which is already defined in the sketch file, so the sketch file should be OK to use as is. After verifying the sketch file looks good, select Sketch > Upload to upload the sketch file to your device.


Arduino IDE TMP361

In the Cayenne dashboard, you can now click the Step 2: Add Sensor button and the TMP36 widget will be added to your dashboard. You can change widget type and settings by clicking on the cogwheel icon in the top right corner of the TMP36 widget.


Arduino IDE TMP361

Actuators

Cayenne works with actuators that are connected to an Arduino. We’ve created sketch files for light, motor, valve, relay and generic actuators.

EXAMPLE: Let’s add a luminosity actuator widget.

For this example, attach a LED to a PWM-enabled Pin on your Arduino Uno. Let’s use D6 in this example. View Luminosity hardware tutorial


Arduino Luminosity Step 2

Click Add New > Device / Widget.


Add New Device

  1. Choose Actuator > Light > Luminosity.
  2. Choose Virtual from the I/O field.
  3. We will use Virtual Pin 1 for this example. Choose V1 from the Pin field.
  4. Click the Step 1: Sketch File button to view the sketch file.


Arduino Luminosity Add Device

A popup will appear showing the Luminosity sketch file. Copy the sketch file contents to the clipboard and open Arduino IDE.


Arduino Luminosity Sketch File

Paste the Luminosity sketch file code into the Arduino IDE. After copying & pasting the example sketch files, you will want to double check that your authentication token is correct as well as update any pin assignments that appear in the sketch file. Read more about using sketch files

In this case, the example sketch file assumes that we used Digital Pin 3 to connect our Luminosity actuator, but we used Digital Pin 6 instead. We will need to update the sketch file to correct the pin. Find and update the LED_DIGITAL_PIN definition so that it points at pin 6.

#define LED_DIGITAL_PIN 6

After verifying the sketch file looks good, select Sketch > Upload to upload the sketch file to your device.


Arduino Luminosity in Arduino IDE

In the Cayenne dashboard, you can now click the Step 2: Add Actuator button and the luminosity widget will be added to your dashboard. You can now use the slider to control the brightness of the LED.


Arduino Luminosity

Custom widgets

We’ve integrated some specific sensors and actuators, but there are thousands of sensors, actuators and other devices that get connected to Arduino boards. Custom widgets allow you to send and receive data from any device that is connected to your Arduino board to Cayenne.

Cayenne Custom Widgets Documentation

EXAMPLE: Let’s see how easy it is to use a Custom Widget in Cayenne. We will switch on an LED connected to your Raspberry Pi using a custom Button widget.

Connect an LED to Digital Pin 8 as shown here. View light switch tutorial


Arduino LED Step 2

Click Add New > Device / Widget.


Add New Device

  1. Select Custom Widgets, then the Button Widget.

  2. Enter the following settings:

    • Widget Name: LED
    • Device: Arduino
    • Connectivity: Digital
    • Pin: D8
    • Icon: LED
  3. Click Add Widget.


Arduino Custom Button Widget

The button widget gets added to your dashboard.


Arduino Add LED

Push the button in your online dashboard to turn the LED on and off. You’re now ready to start using Cayenne for your IoT projects.

Check out other example sketches at our Cayenne Github. Feel free to experiment and combine different examples together to create your own amazing projects.

Troubleshooting

If you don’t see your Arduino device connected to Cayenne, or if you’re running into trouble successfully programming your Arduino with the Arduino IDE, here are a few things to check.

  1. Make sure your Arduino is connected to the Internet

    On most Arduino boards, you will need to connect an Ethernet or Wi-Fi shield in order to connect your board to the Internet. Verify that you have a shield supported by Cayenne installed and working.

    TIP: Double check that the board connection #include in your sketch file is correct for the shield that you are using. The Cayenne sketch file examples assume that you have a W5100 connected. If this line does not match your connection, your board will fail to connect to Cayenne.

    #include <CayenneEthernet.h>
    
    

  2. Make sure your Arduino is connected to a PC/Mac via the USB cable

    Power on your Arduino by connecting your Arduino with a USB cable (or FTDI connector if you’re using an Arduino pro). You should see the power LED lit on your board.

  3. Configure the Arduino IDE

    First, verify that you have the Arduino IDE installed.

    Open the Arduino IDE program and verify that the correct Board is selected.


    Arduino IDE Board Selection

    Next, verify that you have the correct Port selected for communicating with your Arduino. Pick the correct port based upon how you are connecting your Arduino to your PC/Mac.


    Arduino IDE Port Selection

  4. Verify that you have the Cayenne Library installed

    Verify that you see the Cayenne library installed under File > Examples > Cayenne. If you do not, make sure to add it to your Library. For more help on this, see Add Cayenne Library to Arduino IDE.


    Arduino IDE Library Installed

  5. Verify that your Arduino is connected with Cayenne

    You can use the Serial Monitor tool in the Arduino IDE to view some connection information. After uploading your sketch file to the Arduino device, open the Serial Monitor and look for the Cayenne connection.


    Arduino Serial Monitor

    In the output of the Serial Monitor, you should see something like this:

    Getting IP...
    My IP: 192.168.0.10
    Connecting to arduino.mydevices.com:8442
    Ready (ping: 109ms).
    

    If you don’t, this means your board is not connected to the Internet to send data to the Cayenne cloud. You will need to verify that your Arduino is connected to the Internet. If you don’t see any outptut in the Serial Monitor, leave it open and Reset your Arduino board.

LoRa®

Before you can manage your LoRa technology device using the online dashboard, you must make sure your device is setup and add it to your Cayenne dashboard.

LoRaWAN™ setup

Begin by verifying that you have your LoRa network provider account and device information handy, and verify that the hardware is connected to a LoRaWAN gateway in case you are using a private LoRa network (not needed for public LoRaWAN network).

1. Make sure your device is powered on and connected

Your LoRa devices will need to already be connected to either a public or private LoRaWAN network. Contact your network provider if you need help verifying your connection status.

In case of public LoRaWAN network, make sure your devices are powered on and the LoRaWAN coverage of your public network provider is available where you want to use your devices. If you are using a private network, make sure the gateway you will be using is configured and your devices are powered on.

Need a gateway? Here are some helpful links to purchasing and configuring a gateway based on which network you’ll be using.

2. Make sure you have your LoRaWAN account information

If your device has not been previously registered with your LoRaWAN network provider, you will need to provide your account information for the chosen LoRa network. You will only need to enter this information once for each network provider used.

Need an account? Here are some helpful links to creating an account based on which network you’ll be using.

3. Make sure you have the information on your devices being connected

In order to connect Cayenne to your LoRa technology device, you will need to know the DEVEUI for your device. What’s this?

In addition to adding previously activated devices, Cayenne is capable of activating new devices on some LoRaWAN provider networks. If you will be activating your device on the network for the first time, you will also need additional information for the activation process, such as your Appkey or AppEUI. The information required will depend upon which activation mode you select for your device and which network you will be using.

Add LoRa technology device

To begin the process of adding a LoRa device to Cayenne, select the LoRa option from the list of devices. A list of LoRaWAN Networks and supported devices will appear.


step-1-choose-device-category


Add LoRa Device

After selecting the LoRaWAN Network and Device that you want to add, you will then enter in the required settings for adding and activating the LoRa device. Once completed, your dashboard will automatically appear and Cayenne will automatically add widgets for all sensors on your device.


Add LoRa Device


Add LoRa Device

Guided walkthrough

When adding the LoRa device, the settings, supported activation modes and account information required will depend upon which network is selected. Click on the appropriate link below to jump to the section on your network, each of which contains a detailed walkthrough that will help you add your LoRa device to Cayenne.

You can’t perform that action at this time.