Creating a MODE Project

In this tutorial, you will create a MODE project and perform end-to-end communications between a device and an app using simulators. You don’t need to build anything thanks to these simulators.

Step 1: Create a Project

The IoT products you are going to create are organized into projects. As a developer, you can belong to multiple projects. For example, you can have a project for your company and have another project for your personal hobby.

Developers and Projects

Let’s go to the My Projects page on Developer Console and start a new project by clicking the +NEW button.

Screenshot - Creating New Project

Pick a name and write a short description for your project. You also need to decide how the end users of your project will log in. For the purpose of this tutorial, you should select the option Your users will log in with their phone numbers.

Once you have created the project, a new entry will show up in the PROJECT LIST. Select your new project to enter the Project Dashboard.

Step 2: Define a Device Class

An IoT device that is connected to the MODE cloud will be an instance of a device class. If you produce hundreds or thousands of IoT products and they behave the same way, they are in a device class.

Device and Device Classe

For your first hardware product, let’s define a device class. Go to Devices section and click the +NEW button of DEVICE CLASSES to define a new device class. Again, all you need are a class ID (e.g. smart_light) and a short description.

Screenshot - Creating New Device Class

Step 3: Instantiate a Device

Once you’ve defined a device class, you are ready to create device instances. If you have two of the same product, you will create two device instances on MODE. If you manufacture 1,000 of the same product, you will create a thousand entries.

(You need to provision entries for your device instances ahead of time, unless your project was configured to allow On-Demand Device Provisioning. You don’t need to worry about that at this time.)

Let’s create just one device for your smart_light device class. Go to the Devices section, select smart_light from DEVICE CLASSES and click the +NEW button of DEVICE LIST.

The Tag field in the form is optional. Click the ADD button to create a new device.

The device you created is shown in the list. Click the row of the newly created device to show the detailed information of the device.

Screenshot - Device List

It has API Key and Claim Code and other status information. We will look into these later.

Screenshot - Device Details

Step 4: Define an App

An app is software that lets your users control the devices they own. For example, if you plan to write a mobile app to control the devices you make, you need to create a definition for the app.

Routing Device Commands

Let’s create an app. Click the Apps section and click the +NEW button. It will show an app creation form. Pick an App ID to uniquely identify the app (say, controller_app). You should provide a short description as well.

Screenshot - Creating New App

Step 5: Becoming a User of Your Project

You now have a project with a device class and an app. Also, your project has a device instance. What you’ve done so far are tasks of a developer.

From here on, you are acting as a user (i.e. customer) of your project. Typically, a user would buy your hardware product and download the mobile app that goes with it.

Although you haven’t created any actual hardware or mobile app yet, you can simulate the environment that your user will experience by using the Device Simulator and the App Simulator.

Register as a User

Go to the Apps section of Developer Console. Locate the entry for controller_app from APP LIST and click the LAUNCH SIMULATOR button. The App Simulator sends API requests as if it is the actual mobile app.

The first thing you need to do as a user is to register yourself by clicking the REGISTER NEW USER button. Remember that when you first created this project, you selected the option to let users log in with their phone numbers. We recommend this option for projects that use mobile apps as the main user interface, since it allows convenient and secure login from a mobile phone.

Enter your name and a phone number that you can receive a text message. MODE then sends a text message with an authentication code to that phone number.

Screenshot - User Registration

Type the authentication code you receive into the App Simulator and click Submit. You are now logged in as a user of your project.

Screenshot - Entering Auth Code

Create a Home

Home is a place where devices are connected to. Members of a home can control devices that are connected to the home and a user can belong to multiple homes.

Once you are logged in, you are on the My Homes screen. Click the + NEW button to create a home for you. Enter a name for the home (e.g. “My home”), and click the Add button to create a new home.

Powering on the Device

After purchasing a device from you, a user will power it on and connect it to the network. The Device Simulator can simulate these steps.

Open Developer Console, click the Devices section and click smart_light from the DEVICE CLASSES list. Click the first device from DEVICE LIST to show the Device Details page.

Click the LAUNCH SIMULATOR button to start a Device Simulator for that device. This is equivalent to powering on the device.

Claiming Device Ownership

The device is now “powered on”, but you (as a user) haven’t claimed the ownership of the device yet.

To claim the ownership of a particular device, a user needs to know the claim code of the device. Each device is assigned a unique claim code, which is a 16-digit hex string like 1234567890abcdef.

Typically, claim codes are shipped with the hardware (e.g. printed on the packaging). But for the purpose of this guide, you can find the claim code from the Device Simulator in the DEVICE INFO panel.

Screenshot - Device Simulator

Enabling the Claim Mode

MODE allows users to control the claimability of devices to prevent others from stealing a device’s ownership from the legitimate owner. A device is only claimable when its claim mode is enabled.

Let’s turn on your device’s claim mode on the Device Simulator. Click the CLAIM MODE button in the DEVICE INFO panel. The Device Simulator only enables the claim mode for 5 minutes. Once it expires, you can click the CLAIM MODE button again to re-enable claim mode.

Screenshot - Claim Mode

Claiming the Device

Using the App Simulator, you can claim a device while it is in claim mode.

On the App Simulator, go to My Homes and select the home you created. In the HOME INFO panel, select the Devices menu item. This shows the list of devices currently in the home. Click the + NEW button of the DEVICES panel to claim the device. A form with a Claim Code field is shown. Copy and paste the claim code from the Device Simulator and press the Add button.

Now, the device is owned by you (as a user) and you can control the device from the App Simulator!

Step 6: Sending a Command to a Device

One thing you want to do is controlling a device from your mobile app. After all the steps you have gone through, you are now ready to simulate that.

(The Device Simulator should have connected to the MODE cloud via WebSocket already and started waiting for incoming commands. But if it hasn’t, you will notice a green CONNECT button in the DEVICE INFO panel. Click the button to start the connection.)

To send a command, select the Commands / Events menu item in the HOME INFO panel. You are presented with the OUTGOING: COMMANDS panel. Select the device from the Target drop-down list and provide the command details.

A command consists of action and parameters. Action is the name of the command. Let’s use light as the action. For the parameters, let’s set the parameter on to 1:

Screenshot - Send Command

Once you’ve entered all the data, click the Send Command button. The specified command is then sent from the App Simulator to the MODE cloud, and delivered to the target device.

App and Device Simulators

On the Device Simulator, you should see the command being shown in the INCOMING: COMMANDS panel:

Screenshot - Viewing Commands

Click on Details to see more information on the command:

Screenshot - Viewing Command Details

Step 7: Triggering an Event from a Device

A device can also communicate to the cloud, in the form of events. Your apps can listen to these events.

Go back to the Device Simulator and trigger an event. In the OUTGOING: EVENTS panel, enter light-status for Event Type. For Event Data, let’s set the value status to on:

Screenshot - Triggering Events

Click Trigger Event to send the event to the MODE cloud. In the INCOMING: EVENTS panel of the App Simulator, you should see something similar to the following:

Screenshot - Incoming Events

Click on Details to see more information on the event:

Screenshot - Viewing Event Details

Conclusion

You have now successfully configured a small project where you can perform some key actions on MODE. You can control a device from your apps. You can also communicate state changes from a device to your apps. On top of these two way communications, you have set up device and user management for your product.

In the next tutorial, we will replace the device simulator with real hardware. You can proceed to one of the following tutorials next: