Cumulocity Get Started Tutorial
This MIMIC MQTT lab demonstrates integration of Cumulocity IoT and MIMIC MQTT Simulator to produce an out-of-the-box lab for immediate first-time setup and use of dynamically controllable devices . By having a quick, successful example, you will short-circuit integration of your own devices into Cumulocity.
Check out this 3-minute Youtube video of 10 simulated devices updating their device status in Cumulocity in real-time, being graphed in the Cumulocity dashboard.
There are more videos in the Youtube channel listed on the right of this page to show more advanced Cumulocity features, such as events and smart rules.
This lab extends the Cumulocity Getting Started to set up within 5 minutes any number of realistic, third-party, MQTT-based sensors publishing arbitrary telemetry that fits the Cumulocity device SmartREST guidelines. There is no limit to the scalability, but we'll show 1 sensor setup automatically, and then you can try the same yourself on any number in the lab for your requirements (if you need more sensors, send e-mail to email@example.com).
Features of this lab include:
- no prior requirements except for a valid Cumulocity account, ie. a Cumulocity login ;
- no extra setup of hardware, NODE.JS, or cloning of Github source code;
- step-by-step, clear instructions for all tasks;
- 1 realistic sensor (or more) that publishes telemetry via MQTT ;
- each sensor is authorized to access your account (and only your account) in Cumulocity, just like real devices will have to be;
- dynamic telemetry published over the internet to Cumulocity and reflected in the device state;
- real-time, interactive control of the telemetry to reproduce any scenario you want at any point in time;
- investigate all aspects of Cumulocity interaction with a third-party device;
- finally, verifiable cleanup of everything we setup automatically.
These are the tutorial steps you are going to perform to get going quickly:
The power of MIMIC is not limited to this. If you have a scenario you need simulated, send e-mail to firstname.lastname@example.org.
Step 1: Setup
Setup a temporary user in Cumulocity for this lab. This guarantees that any outside access only goes through this temporary user. Later, when you remove the user, all further access will be denied.
NOTE: NEVER give out your Cumulocity tenant login username and password to anyone you don't trust. Whenever we talk about a username and password in this lab it is for the separate, TEMPORARY user that you add with specific limited role(s) as in this Setup step.
This procedure is shown in this 1-minute Youtube video . You can follow along step-by-step by just pausing the video as needed.
To setup your lab, we recommend 2 web browser (Chrome, Firefox, ...) windows side by side. For example in the left browser window you can have your MIMIC MQTT lab for Cumulocity, and in the right your Cumulocity cockpit, logged into your Cumulocity tenant, eg. as in Figure 1:
Figure 1 - 2 browser windows side-by-side
You can maximize either of them when working in one window for a while. When you press README or Help in the MIMIC browser window, it will open another tab with the help text. Clicking on links in this document to external pages will also open in separate tabs. That way you can switch between the tabs, or lay them out however you wish.
Click on Cumulocity Tutorial, then the top README menu item, and the help page titled Documentation: MQTT Lab for Cumulocity appears in a new browser tab. Close the tab by clicking on its x, or switch back to the previous tab.
NOTE: the following is the most complicated part of the tutorial, because we cannot automate it for you, and it shows you what is involved with Cumulocity for when you have to do everything yourself.
We first follow the steps from the User Guide
section to create a separate, temporary user to allow access from this
In the right browser window, in your Cumulocity Cockpit, just click the top right << menu.
Click ADD USER under QUICK LINKS and a new page with title Cumulocity - Administration appears. It should then say New user in the top left, as shown in Figure 2:
Figure 2 - New user
Give the new user a simple, yet memorable Username, for example mimic-lab. The e-mail address for the Email field needs to be real, because Cumulocity will send password reset messages to it.
NOTE: since this is a temporary user that you control, you can put in any e-mail address that it accepts. If you can allocate a new address in your company, use that. Else, the only way we have found is to use a Gmail address, then unselect Send password reset link as email and enter your password here.
In Global roles you will need to assign the user the correct
to be able
to interact with the Cockpit and devices, at least Cockpit User
and business to be able to login to the Cockpit. If you run
into restrictions reported by Cumulocity while investigating advanced
features, you might need to enable additional roles.
Click on Cumulocity Tutorial, then Step 1: Setup....
The shorthand for this will be from now on
Cumulocity Tutorial -> Step 1: Setup....
The Step 1: Setup dialog appears.
For the Tenant Domain, enter the part of the URL that you access
your tenant with. For example,
if you access your tenant as https://mytenant.cumulocity.com,
you would use mytenant.cumulocity.com.
Copy/paste the Username and password from above into
each the respective fields in the dialog, then press OK.
- Once you click OK, a new Run Script Console tab is opened in the browser with the output of the processing. When it says Task completed, and there are no ERROR messages, your lab is configured to work with your Cumulocity tenant with the authentication parameters (username and password) you supplied.
Step 2: Add Device(s)
The left MIMIC MQTT lab browser window shows red icons, one for each simulated device. This is the equivalent of your real-world devices sitting on your lab bench. They are not doing anything.
We need to configure one of the devices to publish telemetry to Cumulocity IoT according to the Cumulocity IoT Device Management rules. This task configures the simulated devices to use the access parameters (username and password) that you configured in Cumulocity IoT.
Let's first check on the devices in your Cumulocity IoT tenant.
To view devices in the Cumulocity Cockpit window, again click the top right << menu. Click on the DEVICE MANAGEMENT icon under QUICK LINKS, and a new page with title Cumulocity - Device management appears.
Click on the top left >> menu, then select Devices, then All devices. There should be no devices, if this is a fresh tenant. Else, it will show the devices that are registered in this tenant. There should be no devices from this lab until the next step.
Click on Cumulocity Tutorial -> Step 2: Add Device.... The
Step 2: Add Device dialog appears.
Figure 3 - Step 2: Add Device dialog
Type the Prefix for the NAME of the device to be created in your Cumulocity tenant. We recommend to keep mimic, that way you can find it easily later. The first device will be mimic-1.
Once you click OK, a new Run Script Console tab is opened in the browser with the output of the processing. When it says Task completed, and there are no ERROR messages, your new sensor device is configured in the MIMIC MQTT Lab, ready to connect to your Cumulocity tenant. You can dismiss this tab, or switch back to the lab browser tab titled Cumulocity IoT Lab.
If it does not have it already, when you now reload the MIMIC MQTT Lab window, the first icon should have a name underneath its number, eg. the first device will be named mimic-1. It is red because it is currently stopped. This is the equivalent of the device sitting on your lab bench in the real world with power switched off.
We configured a new device with name mimic-1 and configured it with the authentication parameters necessary to connect to Cumulocity IoT;
Using the lab
To start using the lab, first verify that at least one device with the chosen prefix, eg. mimic-1, is showing in your MIMIC MQTT Lab.
Step 3: Start Device(s)
The devices in your lab are stopped, equivalent to lab equipment sitting on your lab bench and powered off. So they are not doing anything. We need to power up the recently configured device, the one that is labelled mimic-1.
To start it, select the icon(s) of the device(s) you want to start. Each selected device will have a blue indicator in the upper left. Then click on Cumulocity Tutorial -> Step 3: Start Device(s) -> Go!.
The selected icon(s) will turn green, as if you had turned power on.
Just like the equipment on your lab bench, whether it delivers telemetry to Cumulocity IoT or not depends on whether you have configured the correct parameters in the MQTT client software.
In this lab, if you added the device as in the section above and there were no errors, then it will publish telemetry once a second. You will know that it works when a orange <--> arrow appears in the icon, indicating activity.
In your Cumulocity Iot Device Management All devices page, you can click Reload and it will show the new mimic-1 device as shown in Figure 4:
Figure 4 - Step 3: Device Management
Click on the name of the device, eg. mimic-1, and the device information page will appear. Click on Measurements on the left hand menu, and you the telemetry will be updating. In particular, we made it so that the Light value changes frequently at random, like a flickering light as in Figure 5:
Figure 5 - Step 3: Device Telemetry
The icon of the selected device shows green to indicate that it is started, and telemetry is published to Cumulocity IoT. Now you can investigate further how things work, and change telemetry on the fly.
Step 4: Investigate
Now that it is running, you'll want to see how the lab device and your Cumulocity IoT device state are linked. That way you can reproduce this with your real devices.
To check the configuration of the device in your Cumulocity IoT Device Management page, click on the device name, and then click Info on the left.
To check the configuration of the simulated device in MIMIC, select the device icon in the lab, then click on Cumulocity Tutorial -> Step 4: Investigate -> MQTT Configuration...
Figure 6 - Step 4: MQTT Configuration
The important configuration parameters for the device are the
Config File - this defines the MIMIC simulation: what MQTT payload
to send where and when. Here we publish once a second the telemetry to
the device topic with a SmartREST message containing the desired telemetry.
The Light value changes at random for this tutorial. This simulates a very dynamic attribute that changes at every sample.
Finally, the Temperature values can be dynamically controlled to achieve on-demand, consistent, real-time results, eg. in the Step 5: Change Telemetry section below.
Broker - your Cumulocity IoT tenant broker
Port - 1883 for insecure MQTT communications for now
ClientID - set to the device name
Username - set to your temporary user username
- Password - set to your temporary user password
These are the configurables you would have to setup in your real-world device to communicate with Cumulocity IoT.
NOTE: The OK button is disabled in this lab. More advanced labs allow you to configure anything on the simulated devices.
We verified the necessary configuration for a device to communicate with Cumulocity Iot.
Step 5: Change Telemetry
You are seeing real-time, dynamic telemetry in your digital twin on Cumulocity IoT. The Temperature value is static, while the Light value changes at random, like a flickering light. In this task we will interactively change the temperature to some other predictable value. This lets you change the temperature on-demand, eg. a device over-heating. Imagine the effort to do this with a real device.
If you have not done so already above, in the MIMIC lab window select the icon(s) of the device(s) you want to manipulate and start it. Each selected device will have a green icon and a blue indicator in the upper left. Then click on Cumulocity Tutorial -> Step 5: Change Telemetry....
In the Step 5: Change Telemetry dialog, change the Temperature value to something else, eg. 60000. As soon as you click OK, the new temperature value is published.
Figure 7 - Step 5: Change Telemetry
In your Cumulocity Iot Cockpit, you can click on the thing that you started, then go to its Shadow, and the new temp telemetry will be reflected.
We changed temperature telemetry on the fly, on-demand, predictably. You can use this technique when it comes to testing your application for certain conditions.
Step 6: Stop Device(s)
Your lab devices are continuously generating telemetry and publishing messages to Cumulocity IoT. This task stops them, the equivalent of powering down the real equipment.
In the MIMIC lab window select the icon(s) of the device(s) you want to stop. Each selected device will have a blue indicator in the upper left. Then click on Cumulocity Tutorial -> Step 6: Stop Device(s).
The icon(s) will turn red, and messages cease to be published.
We stopped the devices to stop publishing messages.
Step 7: Advanced Tasks
These are further optional tasks you can do in your lab:
Step 2: Add Device
, and it will add more things with incrementing instance number upto
the total allowed in your lab. Once you start the lab devices,
you will see independent telemetry for each;
edit a device in Cumulocity IoT Device Management to add it to a
to manage collections of your devices;
and apply it to your device in order to constrain and categorize it;
to display the telemetry any way you want, eg. by following this
- test smart rules to act on the telemetry received, as shown in this 2-minute video ;
Step 8: Cleanup
Once a lab is setup, you want to clean it up when you are done, to be certain no left-over devices have access to your account. This procedure makes certain there are no left-overs.
The Cumulocity Tutorial -> Step 8: Cleanup... lets you cleanup devices setup in the lab. Just select the device(s), then that menu item cleans up any associated resources from both Cumulocity IoT and the MIMIC MQTT Lab.
Once you have deleted a device, you can add one back in with different credentials with the Add step above.
To clear the rest, as detailed for Q: What about security / privacy? in the next section, ie.:
- remove the temporary user, eg. mimic-lab in your Cumulocity IoT Administration application that you used in the Setup step above. Once you do this, you no further operations will work in this lab until you setup again with a new temporary user.
Frequently Asked Questions
- Q: What will this cost me?
A: Besides the fixed cost for the MIMIC MQTT lab, there will be Cumulocity IoT costs in your Software AG account that we cannot control, beyond their free evaluation.
- Q: What exactly does this do to my Cumulocity account?
A: You setup a temporary user in the above Setup.
If you run the Step 2 - Add dialog with correct Cumulocity authentication parameters, and start the device, it will setup exactly 1 device instance in your Cumulocity tenant. Any subsequent devices connecting to Cumulocity from this lab will be added as well.
Since we NEVER know your tenant authentication parameters, we cannot do anything else to your account.
- Q: What about security / privacy?
A: The lab will be able to access your account during the session because authentication parameters (username and password) are stored in the lab configuration. You can delete the temporary user that you created in the Setup section above. Then you can verify that the devices can no longer talk to your account. This is verifiable cleanup, ie. you have proven that the outside device cannot access any more.
- Q: Where can I get help?
A: For the MIMIC lab select the README menu item, or press the Help button in any dialog. If you still need help, send e-mail to email@example.com.
- Q: What next?
A: This lab gives you a small successful step in connecting a few third-party sensors publishing real-time, dynamic, predictable, controllable telemetry to Cumulocity IoT in a matter of minutes. The next steps are up to you:
- You can build on what you learned to connect your own devices to
Explore our other free resources / videos to learn about solutions to
common problems you will encounter in IoT development;
rent an advanced lab
anytime you need to test different aspects of your
application, or lease a longer-term
MIMIC MQTT Simulator
with more features;
- You can scale the deployment to as many devices as you need to test, demo, train your IoT Application.
- You can build on what you learned to connect your own devices to Cumulocity IoT;