In Creating a MODE Project, we simulated a virtual device from the Developer Console. Now we will build a real hardware device from a Raspberry Pi and make a "smart" light -- an LED light that can be turned on and off via MODE, from anywhere in the world.

Required tools

  • Raspberry Pi | You can use any version
  • AC adapter | 5V at 0.5A or more.
  • SD card | 8GB or bigger.
  • Jumper wires (female/male) | To connect components and Raspberry Pi. We need two wires.
  • Solderless breadboard | For assembling components.
  • LED | Any color.
  • Resistor | Anything between 330 to 1k ohms.
  • USB WiFi module (optional) | Alternatively, you can use onboard Ethernet port on Raspberry Pi.

Step 1: Set up Raspberry Pi to Connect to the Internet

Let's set up the Internet environment on the Raspberry Pi. In this tutorial, we use Linux distribution called Raspbian for the Raspberry Pi's OS, because it is well maintained and installing the latest Node.js Debian package is easy.

If you already have your Raspberry Pi installed with Raspbian, please skip this step and go to Step 2.

Go to the Raspberry Pi download page and go to the RASPBIAN section. Click 'Download ZIP' for "Raspbian Buster with desktop and recommended software". The file is archived with ZIP, so you have to unzip command the file first. On macOS, you can double click the file to extract or you can use the unzip command.

The extracted file will be 2020-02-13-raspbian-buster-full.img or <timestamp>-raspbian-<version name>.img.

Once you've unzipped the file, you have to burn the image into a SD card or microSD card. If you're using a MacBook Pro, you can use the SD card slot. Your PC laptop may have it too. Otherwise, you can buy a pre-installed SD card from here.

If your PC has an SD card slot, please visit the installation page and follow the instructions.

Once you've finished making the OS image, insert the SD card into your Raspberry Pi and make sure it boots. You will be prompted for set up of the Raspberry Pi including location and WiFi settings. You are making a real "Internet of Things" device, so connection to the Internet is mandatory :-). Alternatively, you can just plug an Ethernet cable from Raspberry Pi to your home router.

Once connected to the internet, make sure you can SSH to it from your computer.

Please make sure you can reach to the MODE cloud from your Raspberry Pi with the following command on your terminal.

$ curl

If you can see the following message, your Raspberry Pi is ready to connect to MODE (Version number could be different).

{ "server": "api-server", "version": "2.40.0-rc.5" }

Step 2: Install Node.js onto Raspberry Pi

To control the LED and connect to MODE Cloud, we use Node.js to run our device program. Raspbian's Node.js package cloud be quite old (version 0.10.x) and we prefer more recent versions.

To check and install a stable and new binary version of Node.js from

For the old Raspberry Pi Model B, we can use node-<version>-linux-armv6l.tar.gz. For Raspberry Pi 3, we can use node-<version>-linux-armv7l.tar.gz.

$ wget
$ tar xvfz node-v13.9.0-linux-armv7l.tar.gz
$ cd node-v13.9.0-linux-armv7l
$ sudo cp -R * /usr/local/
$ node -v


When you set up your Raspberry Pi and install the Node.js runtime environment, you may see the following error message:

"GLIBCXX_3.4.20" & "GLIBC_2.16" are not found (required by node)

In that case, please follow this instruction.

Step 3: Download LED Controller Code

Download the "Blinker" sample application from Github to your home directory. You can download them with the following commands:

$ cd ~
$ git clone

Once you've downloaded the files, run the following command to install the mode-device and onoff libraries. mode-device takes care of Mode Could API connection and onoff controls GPIO access and interrupt detection on Raspberry Pi.

$ npm install

If you don't see any error messages, the mode-device and onoff libraries have been correctly installed and the demo is ready to go!


As of May 2016, one of the npm package onoff fails to compile.

You can run following command to fix the problem:

$ sudo apt-get install gcc-4.8 g++-4.8
$ sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-4.6 20
$ sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-4.8 50
$ sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-4.6 20
$ sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-4.8 50

Step 4: Configure Device Information and API Key

For a device to communicate to MODE, we need two pieces of information: a Device ID and an API Key.

Since you've already created a project for smart_light device class in Getting Started with MODE guide, we will use that project for this tutorial too.

Launch Developer Console and select Devices section. From DEVICE CLASSES, choose smart_light.

By clicking the previously created device from the DEVICE LIST, you can find the Device ID and API Key in the details page of the device. These are the information you need to copy to your Raspberry Pi. Also make sure the device is attached to a home (you see an id in Home ID field).

Screenshot - Device Details

Please open the app.js file with your favorite editor (vim or nano) and find the following lines:

var DEVICE_ID = 1
var API_KEY =

Please replace your DEVICE_ID number and API_KEY according to your device information. Once you've filled in the information, your device program is ready to run.

As you are starting a real device, make sure you close Device Simulator window if you previously used.

Step 5: Test the Device Connection

To make sure your configuration is correct, go to the Developer Console, locate the app you created in the Basic Project Setup tutorial, and launch its App Simulator. On the simulator, select the home you have previously created. The simulator is now listening to events coming from devices of this home.

Once the app simulator is ready, run the following command from your Raspberry Pi terminal:

$ node app.js

If your setup is correct, You should see the following output on your Raspberry Pi:

[MODE-DEVICE] Triggering event #1
[MODE-DEVICE] Reconnect websocket in 0 seconds
[MODE-DEVICE] scheduling a reconnection
[MODE-DEVICE] Socket is allocated to event #1
[MODE-DEVICE] scheduled reconnection triggered
[MODE-DEVICE] Reconnecting websocket
[MODE-DEVICE] Connecting to wss://
[MODE-DEVICE] Event #1 triggered
[MODE-DEVICE] Websocket client is connected

This means your Raspberry Pi has successfully connected to MODE and is waiting for commands from it.

You can confirm the connection to the cloud from the Device Detail page of the Developer Console.

Reload the page and you should see "Received event [first_event] from device #1" in LOGS section on the Developer Console (Developer Console > Select Project > Devices > Select Device Class > Instances > Select Device Instance > System Logs)

Screenshot - Incoming Events

Now the device software is ready, we can start the hardware assembly.

Step 6: Configure Your Hardware

Before you start, make sure you shut down and power off your Raspberry Pi to avoid shorting any circuits while working on wiring.

$ sudo shutdown -h now

In your Raspberry Pi, please find the GND and GPIO4 pins. On Raspberry Pi 3, they are pin 25 and pin 7 on the GPIO pins. On Raspberry Pi 2, they are pin 39 and pin 7.

Screenshot - LED Wiring

Wire the actual hardware. Please connect the LED, the resistor, GND and GPIO4 to the breadboard in the following order:

  1. Connect GPIO4 to LED's longer leg
  2. Connect LED (shorter leg) to the resistor
  3. Connect the other leg of the resistor to GND pin of Raspberry Pi

Specifically, the order of the LED's longer or shorter leg is very important. If you connect the wrong side, the LED won't turn on.

If you know how to deal with breadboards, just make sure all the components are electrically connected. If you don't know how to connect those components on the breadboard, here are more detailed instructions.

Breadboard Wiring Steps

If this is the first time you use a breadboard, please make sure the breadboard has numbers and alphabets on columns and rows. We can specify a hole with <number>-<alphabet> where we should attach the components.

  1. Attach the female connector of a jumper to GPIO4 male pin on Raspberry Pi.
  2. Attach the male pin of the jumper to the hole 7-a of breadboard.
  3. Attach the longer leg of LED to 7-d.
  4. Attach the shorter leg of LED to 10-d.
  5. Attach one leg of the resistor to 10-b.
  6. Attach the other leg of the resistor to 14-b.
  7. Attach the male pin of the jumper to 14-a of breadboard.
  8. Attach the female connector of a jumper to GND male pin on Raspberry Pi.

Once you've set up the breadboard, it should look like the picture above.

Now your hardware setting is ready.

Step 7: Send Commands from App Simulator to Raspberry Pi

Once you finish the wiring, power your Raspberry Pi on again. If you see any smoke, sparks or detect any weird smell, your hardware circuit setting would be wrong, and you should shut down the power immediately.

Log in to the Raspberry Pi and run the following command on your terminal again:

$ node app.js

Sending a Command to Raspberry Pi

Let's send a command from the App Simulator to turn on your light. Go to the OUTGOING: COMMANDS panel, select the device from the Target drop-down list and provide the command details.

The sample program implements the light command. So enter light for action and for parameters, use switch for key, and 1 for value:

Screenshot - Send On Command

Once you've entered all the data, click the Send Command button. The command is then sent from the App Simulator to the MODE cloud, and delivered to the Raspberry Pi.

Now you should see the LED switching on.

LED Turned On

If you want to turn it off, simply re-enter a value of 0 for the switch parameter:

Screenshot - Send Off Command

And click the Send Command button again. The LED is now turned off.

Congratulations! Your Raspberry Pi is now controllable via MODE. You can send command from anywhere from your office, your home, or even from your mobile phone.


If you cannot see the LED switching on/off, please check the logs on the terminal of the Raspberry Pi. The logs should be similar to the following:

Received raw message: "{"action":"light","parameters":{"switch":1}}"
Received flag: "[object Object]"
Command handler is called
Received raw message: "{"action":"light","parameters":{"switch":0}}"
Received flag: "[object Object]"

If you can see the logs and you cannot turn the LED on and off, it means your hardware configuration is wrong. Please check that all components are correctly connected in the order as shown in the previous section. If you cannot see the logs, software or network connectivity may be the problem. Please go back to Step 4, and check your software configurations.


In this tutorial, we showed you how you can control an LED connected to a Raspberry Pi from the app simulator. You now have a real hardware connected to MODE and it is securely controlled by the owners of the device.