Introduction


In this tutorial, you will create a MODE project and perform end-to-end communications between a device and an app using simulators. This includes creating a project, creating device classes, creating an app, and registering a user.

An important note on user registration and authentication for the MODE platform: There are three methods for user authentication:

  1. Authentication by email
  2. Authentication by mobile phone (SMS)
  3. Authentication by account system between users independent of MODE Platform.

Although there are multiple user authentication methods as described above, email authentication will be explained in this chapter. Please refer to User Accounts and Authentication for other authentication methods.

Step 1: Create a Project


A Project in MODE is the core of your IoT system. After signing in to MODE Developer Console, select My Projects from the menu on the side and click on + NEW to create a new project.

Enter a “Name” and “Description” for the project.

Select the option “Your users will log in with their email addresses” in User Accounts. Bear in mind that this selection cannot be changed after creating a project. Click on the Save button to create your new project.

If you accidentally selected the wrong selection for user authentication and created a project, delete the project and create a new one.

Screenshot - Create Project Settings

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


Now, we will create a device class. A Device Class is a logical grouping of MODE’s virtual devices (e.g. a Gateway). Select Devices from the menu on the left and click the + NEW button on the right end.

Screenshot - Create New Device Class

Enter a Class ID and Description, then click the SAVE button to create a new Device Class.

Screenshot - Create New Device Class Settings

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 have 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 first_device_class device class.

Screenshot - Device Class List

Select the Instances tab.

Screenshot - Device Instances

Select + NEW on Device List page.

Screenshot - Device Instances New

Select + ADD on Device List page. The Tag field in the form is optional. By default, the device's channel will be stable, but other firmware channels can be selected. Additionally, the associated bundle can be customized based on available firmware bundles. Click the ADD button to create a new device.

Screenshot - Adding a Device Instance

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 such as the API Key, Claim Code and other status information. We will use these pieces of information later.

Screenshot - Device Instance Settings

Here, you can also launch the device simulator. The Device Simulator virtually simulates a physical device such as a Gateway. Leave the simulator running and return to Console. We will return to the Device Simulator in a later step.

Screenshot - Launch Device Simulator

Step 4: Create an App


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

Apps are also where you can register a user through MODE Console.

Diagram - Routing Device Commands

Navigate to the the Apps section and click the +NEW button. Enter an App ID to uniquely identify the app (e.g. controller_app). Provide a short description for the app as well.

Screenshot - Creating New App

Select the App created to view the App Settings.

Screenshot - Apps Settings

Here, you can launch the App Simulator as well. Select the LAUNCH SIMULATOR button in App Simulator to open an App Simulator. This will open in a new window.

Screenshot - Apps Settings New

Step 5: Register a New User


You now have a project with a device class, an app, and 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 use the app that goes with it.

To register a user using the App Simulator, click on the REGISTER NEW USER button.

Screenshot - Apps Simulator Register New User

Enter the name, email address and password of a user you would like to register and click REGISTER.

Screenshot - Apps Simulator Register New User Details

An email titled “Verify your Example Project Account” will be sent to the registered email address. Click on the URL provided in the email to complete activation. Then, click on the I’M VERIFIED button on App Simulator to complete user registration.

Screenshot - Apps Simulator Register New User Verification

Step 6: Create a Home


A Home in MODE 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.

In our example, we are logged in as the user "John". 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.

Screenshot - Apps Simulator New Home Settings

Select the new Home just created.

Screenshot - Apps Simulator Home List

Select Members.

Screenshot - Apps Simulator Members Button

John, who created the Home, is registered as the first member. The first user registered on Home has the Owner role.

Screenshot - Apps Simulator Members List

Step 7: Add a Device To a Home


We will associate the device instance created in the previous steps.

To claim the ownership of a particular device to a Home, 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.

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

Diagram - 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 8: 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.