| Line 1: |
Line 1: |
| | [[File:Networking rut telekom logo.png|right|160px]] | | [[File:Networking rut telekom logo.png|right|160px]] |
| − | '''Telekom Cloud of Things''' is now compatible with Teltonika RUT routers. | + | '''Telekom Cloud of Things''' is now compatible with Teltonika RUT2xx, RUT9xx and RUTXxx series routers. |
| | ==Description== | | ==Description== |
| | | | |
| − | The '''Cloud of Things''' is cloud platform for the Internet of Things. It allows you to remotely monitor, manage and control your connected devices and machines – plug-and-play, without extensive installation. | + | The '''Cloud of Things''' is a cloud platform for the Internet of Things. It allows you to remotely monitor, manage and control your connected devices and machines – plug-and-play, without extensive installation. |
| | | | |
| | ==Summary== | | ==Summary== |
| | | | |
| − | This example application streams some information from the router device. Once it is enabled you should be able to the following things in Cloud of Things Cockpit the following information from your router: | + | This example will provide steps on how to connect your device to Cloud of Things. |
| | | | |
| − | Device Model, Revision and Serial Number
| + | There are many things that you can monitor via this platform: |
| | | | |
| − | Mobile Cell ID, ICCID, IMEI, Connection Type, Operator, Signal Strength
| + | Device Data - Device Model, Revision and Serial Number |
| | | | |
| − | WAN Type and IP
| + | Mobile data - Mobile Cell ID, ICCID, IMEI, Connection Type, Operator, Signal Strength |
| | | | |
| − | Mobile and WAN information are sent from “stream” Lua script, while Device information - from stream application. This information (except Device) is being sent to the main Cumulocity server continuously: at 10 seconds interval.
| + | Network info - IP |
| | | | |
| | + | Availability |
| | | | |
| − | ????????????????????????????????
| + | And other... |
| | + | ==Creating an account== |
| | + | First of all, you need to create an account. After registration, you will receive free 60 days Cloud of Things trial. Registration form can be found here: https://support.ram.m2m.telekom.com/apps/demotenant/index.html#/ . Below you can see a picture of the registration form: |
| | | | |
| − | ==Creating an account==
| |
| − | First of all, you need to create an account. After registration, you will receive free 60 days Cloud of Things trial. Registration form can be found here:https://support.ram.m2m.telekom.com/apps/demotenant/index.html#/ . Below you can see registration form:
| |
| | | | |
| | [[Image:CoT_Demo_Account.png]] | | [[Image:CoT_Demo_Account.png]] |
| | | | |
| − | '''Note:''' The value in URL field will be your Cumulocity server address.
| |
| − |
| |
| − | After successful registration, you can log in by entering the same full URL you have used in registration form. In this example it is myservername.cumulocity.com. Then navigate to: https://myservername.cumulocity.com and after logging in, you will be redirected to Cumulocity Cockpit portal, see below:
| |
| − |
| |
| − | [[File:cumulocityportal.png]]
| |
| − |
| |
| − | ==Preparing firmware with example application==
| |
| − |
| |
| − | First, you need to obtain GPL from https://teltonika-networks.com/gpl. Now you need to run “make menuconfig” command inside GPL folder.
| |
| − |
| |
| − | [[File:cummakeconfig.png]]
| |
| − |
| |
| − | You need to add example application so it can be built. Navigate to “Network” section and select “cmstreamapp” with spacebar key. It will show “<*>” once application is added, see below:
| |
| − |
| |
| − | [[File:cumnetworksection.png]]
| |
| − |
| |
| − | Now do the same with “Luci” section, “Applications → luci-app-iot”. This will enable to configure example package from router control panel, see below for example:
| |
| − |
| |
| − | [[File:cumlucisection.png]]
| |
| − |
| |
| − | Everything should be ready and you can exit. Now run “make” command and firmware will appear in “bin/ar71xx/tltFws” directory. You can flash “GPL_…._WEBUI.bin” file.
| |
| − |
| |
| − | ==Configuring and launching example application==
| |
| − | After you successfully built and flashed firmware, in „Services“ tab there should be an option called „IoT Platforms“.
| |
| − |
| |
| − | [[File:cumiot.png]]
| |
| − |
| |
| − | [[File:cumiotwindow.png]]
| |
| − |
| |
| − | Only single field is required, which is Server Address. This is the same URL of Cumulocity Cockpit website. In this example, it is myservername.cumulocity.com.
| |
| − |
| |
| − | Explanation of other options:
| |
| − |
| |
| − | Use SSL/TLS – connection will use TLS, however, you need to have a signed SSL certificate, otherwise application would not be able to connect to the Cumulocity server.
| |
| − |
| |
| − | Reset Auth – once device has been removed from the Cumulocity Device Management, you will need to reset authentication in order to re-register device.
| |
| − |
| |
| − | Also click „Enable“ to enable example application. See below:
| |
| − |
| |
| − | [[File:cumiotvalues.png]]
| |
| − |
| |
| − | Now click „Save“ and if everything is correct – example application will successfully connect to the Cumulocity server.
| |
| − |
| |
| − | Now you need to register device on Device Management in Cumulocity Cockpit.
| |
| − |
| |
| − | Device registration is done by writing down device's serial number. In order to obtain your device's serial number, look at the backplate of it or navigate to your device's control panel and then to „Status → Device“ page:
| |
| − |
| |
| − | [[File:cumdevice.png]]
| |
| − |
| |
| − | In this case, serial number is 09516845.
| |
| − |
| |
| − | Now log into your Cumulocity Cockpit portal, in this example URL is https://myservername.cumulocity.com.
| |
| − |
| |
| − | Go to the Device Management page:
| |
| − |
| |
| − | [[File:cumcockpit.png]]
| |
| − |
| |
| − | [[File:cumdevicemanagement.png]]
| |
| − |
| |
| − | Then navigate to Registration page:
| |
| − |
| |
| − | [[File:cumdevicepage.png]]
| |
| − |
| |
| − | Click „Register device“:
| |
| − |
| |
| − | [[File:cumdeviceregister.png]]
| |
| − |
| |
| − | Click „General device registration“:
| |
| − |
| |
| − | [[File:cumnewdevice.png]]
| |
| − |
| |
| − | Write device’s serial number in „Device ID“ field and click „Next“:
| |
| − |
| |
| − | [[File:cumdeviceregistration.png]]
| |
| − |
| |
| − | As shown below, registration is successful:
| |
| − |
| |
| − | [[File:cumsuccessresgister.png]]
| |
| − |
| |
| − | Click „Finish“ to close this pop-up. Now if everything is correct, a new device widget should show up with a status „PENDING ACCEPTANCE“:
| |
| − |
| |
| − | [[File:cumpendingdevice.png]]
| |
| − |
| |
| − | Click „Accept“ button to accept this device.
| |
| − |
| |
| − | Now navigate to „All devices“ page:
| |
| − |
| |
| − | [[File:cumalldevices.png]]
| |
| − |
| |
| − | Here you should be able to see list of all registered devices:
| |
| − |
| |
| − | [[File:cumallregistereddevices.png]]
| |
| − |
| |
| − | Click on „TLT-RUT955 Router“ name to get into information page:
| |
| − |
| |
| − | [[File:cumdeviceinfo.png]]
| |
| − |
| |
| − | Notice „Device Data“ widget, it contains information from the router device. By navigating to „Control“ tab, you can restart device by clicking „More → Restart Device“:
| |
| − |
| |
| − | [[File:cumdevicecontrol.png]]
| |
| − |
| |
| − | You can go back to Cumulocity Cockpit page the same way you entered Device managemant page:
| |
| | | | |
| − | [[File:cumnavigatecockpit.png]]
| + | After successful registration you will receive an email with your account details (URL, username, password) and after logging in, you will be redirected to Cloud of Things Cockpit portal, see below: |
| | | | |
| − | Then navigate to „Home“ page:
| + | [[Image:Cloud of things cockpit.png]] |
| | | | |
| − | [[File:cumnavigatehome.png]]
| + | ==RUT2xx / RUT9xx - Package installing and device registering== |
| | | | |
| − | And then click „Add widget“:
| + | Cloud of Things IoT platform is not included in standart software package, so in order to use the feature you will need to install it first. To do so, go to '''System>Package Manager.''' |
| | | | |
| − | [[File:cumaddwidget.png]]
| |
| | | | |
| − | Select „Asset properties“ widget and type title, then select „TLT-RUT955 Router“ in „Target Assets or Devices“:
| + | [[Image:Cloud of things package installing 1.png]] |
| | | | |
| − | [[File:cumcreatewidget.png]]
| |
| | | | |
| − | To add more information into widget, click „Add property“ and click on „Show“ to add that property.
| + | There you will find all the available packages. The one you need is called '''Cloud of Things'''. In order to install it just press the '''Install''' button. |
| | | | |
| − | In example application, these properties are used:
| |
| | | | |
| − | Hardware – Model, Revision, Serial Number
| + | [[Image:Cloud of things package installing 2.png]] |
| | | | |
| − | Mobile – Cell ID, Connection Type, Current Operator, ICCID, IMEI and Signal
| |
| | | | |
| − | WAN – IP and Wan Type
| + | Then it will ask for your confirmation, whether you want to install the package. Press '''OK''' to continue. |
| | | | |
| − | Total properties:
| |
| | | | |
| − | [[File:cumtotalprops.png]] | + | [[Image:Cloud of things package installing 3.png]] |
| | | | |
| − | Then click „Save“ and you should be able to see widget with properties you have set:
| |
| | | | |
| − | [[File:cumdevicewidgetinfo.png]]
| + | It will take a moment to install, but when it is done, you will receive a message. |
| | | | |
| − | ==Explanation of example application==
| |
| − | There are two steps when adding new properties:
| |
| | | | |
| − | 1. Writing template
| + | [[Image:Cloud of things package installing 4.png]] |
| | | | |
| − | 2. Writing lua script which will stream information.
| |
| | | | |
| − | By default, template location inside router is „/usr/lib/lua/cm/srtemplate.txt“. It contains such content:
| + | When the package is installed, a new window in '''Services''' section will appear, '''IoT Platforms'''. |
| | | | |
| − | rut955-v0.01
| |
| | | | |
| − | 10,100,GET,/identity/externalIds/SerialNumber/%%,,application/json,%%,STRING,
| + | [[Image:Cloud of things package installing 5.png]] |
| | | | |
| − | <nowiki> 10,101,POST,/inventory/managedObjects,application/json,application/json,%%,STRING,"{""name"":""%%"",""c8y_IsDevice"":{},""com_cumulocity_model_Agent"":{}}"</nowiki>
| |
| | | | |
| − | 10,102,POST,/identity/globalIds/%%/externalIds,application/json,application/json,%%,STRING STRING,"{""externalId"":""%%"",""type"":""SerialNumber""}"
| + | In order to use the feature, you will need to enable it, write '''Server Address''' and press '''Save.''' The server address is the link which was provided by '''Cloud of Things'''. |
| | | | |
| − | 10,103,PUT,/inventory/managedObjects/%%,application/json,application/json,%%,STRING STRING STRING,"{""name"": ""%%"", ""type"": ""%%""}"
| + | (E.g. example.example.example.telekom.com) |
| | | | |
| − | <nowiki> 10,104,PUT,/inventory/managedObjects/%%,application/json,application/json,%%,STRING STRING STRING STRING,"{""c8y_Hardware"": {""model"":""%%"",""revision"":""%%"",""serialNumber"":""%%""}}"</nowiki>
| |
| | | | |
| − | 10,105,PUT,/inventory/managedObjects/%%,application/json,application/json,%%,STRING STRING STRING STRING STRING STRING STRING,"{""c8y_Mobile"": {""imei"":""%%"",""cellId"":""%%"",""iccid"":""%%"",""connType"":""%%"",""currentOperat or"":""%%""},""signal"":""%%""}"
| + | [[Image:Cloud of things package installing 6.png]] |
| | | | |
| − | <nowiki> 10,106,PUT,/inventory/managedObjects/%%,application/json,application/json,%%,STRING STRING STRING,"{""c8y_Network"":{""c8y_WAN"":{""ip"":""%%""}},""wanType"":""%%""}"</nowiki>
| |
| | | | |
| − | 10,107,PUT,/inventory/managedObjects/%%,application/json,application/json,%%,UNSIGNED STRING,"{""c8y_SupportedOperations"":[""%%""]}"
| + | P.S. In order to re-register a device on Cloud of Things platform, you need to press '''Reset Auth''' button. If you are registering the device for the first time, pressing the button is not necessary. |
| | | | |
| − | 10,108,PUT,/devicecontrol/operations/%%,application/json,application/json,%%,UNSIGNED STRING,"{""status"":""%%""}"
| + | ==RUTX - Package installing and device registering== |
| | | | |
| − | 11,500,$.managedObject,,$.id
| + | Cloud of Things IoT platform is not included in standart software package, so in order to use the feature you will need to install it first. To do so, go to '''System>Package Manager.''' |
| − | 11,501,,$.c8y_IsDevice,$.id
| |
| − | 11,502,,$.c8y_Restart,$.id,$.deviceId
| |
| | | | |
| − | First line contains template version. In this case it is „rut955-v0.01“.
| |
| | | | |
| − | When template is updated, version must be updated aswell, otherwise device will use non-updated template version.
| + | [[Image:Cloud of things rutx package installing 1.png]] |
| | | | |
| − | The following lines contains requests starting with a number „10“ and responses - starting with a number „11“. Now explanation of request:
| |
| | | | |
| − | Type - 10
| + | There you will find all the available packages. The one you need is called '''Cloud of Things'''. In order to install it just press the '''Install''' button. |
| | + | [[Image:Cloud of things rutx package installing 2.png]] |
| | | | |
| − | Code - 101
| |
| | | | |
| − | Method - POST
| + | Then it will ask for your confirmation, whether you want to install the package. Press '''YES''' to continue. |
| | | | |
| − | URL - /inventory/managedObjects
| |
| | | | |
| − | Content Type - application/json
| + | [[Image:Cloud of things rutx package installing 3.png]] |
| | | | |
| − | Accept - application/json
| |
| | | | |
| − | Placeholder - %%
| + | It will take a moment to install, but when it is done, you will receive a message. |
| | | | |
| − | Params - STRING STRING
| |
| | | | |
| − | Template - JSON
| + | [[Image:Cloud of things rutx package installing 4 v1.png]] |
| | | | |
| | | | |
| | + | When the package is installed, a new window in '''Services>Cloud Solutions''' section will appear, '''Cloud of Things'''. |
| | | | |
| − | Type – requests are identified by a number 10
| |
| | | | |
| − | Code – request code number, each request must contain unique number
| + | [[Image:Cloud of things rutx package installing 5.png]] |
| | | | |
| − | Method – HTTP method of request
| |
| | | | |
| − | URL – URL that will be used in request
| + | In order to use the feature, you will need to enable it, write '''Server Address''' select '''Interface''' name and press '''Save & Apply.''' The server address is the link which was provided by '''Cloud of Things'''. |
| | | | |
| − | Content Type – it is Content-Type header field value
| + | (E.g. example.example.example.telekom.com) |
| | | | |
| − | Accept – it is Accept header field value, mostly equal to Content Type
| |
| | | | |
| − | Placeholder - string which will be replaced in URL or Template JSON
| + | [[Image:Cloud of things rutx package installing 6 v1.png]] |
| | | | |
| − | Params – what kind of params are replaced, JSON template contains two strings
| |
| | | | |
| − | Template – JSON template which will be sent
| + | P.S. In order to re-register a device on Cloud of Things platform, you need to press '''Reset Auth''' button. If you are registering the device for the first time, pressing the button is not necessary. |
| | | | |
| | + | ==Adding device(s) on Cloud of Things== |
| | + | After successfully installing the package and making the required configuration on the router, you now can add the device on '''Cloud of Things''' platform, steps for RUT and RUTX series routers are the same. After logging in to the website you are forwarded to Cockpit page. There press '''Device manager'''. |
| | | | |
| − | Explanation of response:
| + | [[Image:Cloud of things adding device 1.png]] |
| | | | |
| − | Type - 11
| + | Then select '''Devices''' and press '''Registration'''. |
| | | | |
| − | Code - 502
| + | [[Image:Cloud of things adding device 2.png]] |
| | | | |
| − | Cond - <none>
| + | Press '''Register device'''. |
| | | | |
| − | Value 1 - $.c8y_Restart
| + | [[Image:Cloud of things adding device 3.png]] |
| | | | |
| − | Value 2 - $.id
| + | There are two ways to register your device(s) '''Bulk''' and '''General'''. Bulk is used when you are registering many devices at once. In this example we will be using the '''General''' option. |
| | | | |
| − | Value3 - $.deviceId
| + | [[Image:Cloud of things adding device 4.png]] |
| | | | |
| | + | In '''Device ID''' section write the serial number of your router. You can add more than one item by pressing '''Add another device''' button. There is a possibility to assign your routers to groups, but we are not doing that in this example. |
| | | | |
| − | Type – responses are identified by a number 11
| + | [[Image:Cloud of things adding device 5.png]] |
| | | | |
| − | Code – response code, each response must contain unique number
| + | If everything was done correctly, it will show you that the registration was successful. |
| | | | |
| − | Cond – JSON path base pointing to an object or object list from which values are
| + | [[Image:Cloud of things adding device 6.png]] |
| − | extracted
| |
| | | | |
| − | Value… - JSON values
| + | Then you will need to '''Accept''' the '''Pending Acceptance'''. |
| | | | |
| − | Take a look for more information about templates: https://www.cumulocity.com/guides/reference/smartrest.
| + | [[Image:Cloud of things adding device 7.png]] |
| | | | |
| − | Now explanation of logic inside lua script. By default, example application’s lua script location is „/usr/bin/lua/cm“. Application will scan this folder for any *.lua files and load them if they contains „init“ function. Script’s „stream.lua“ content:
| + | Finally you will receive a message indicating that the device has been accepted. |
| | | | |
| − | -- stream.lua
| |
| − | local utl = require "luci.util"
| |
| − | local sys = require "luci.sys"
| |
| − | local DEVICE_NAME = 'TLT-RUT955 Router'
| |
| − | local DEVICE_TYPE = 'Router'
| |
| | | | |
| − | function restart(r)
| + | [[Image:Cloud of things adding device 8.png]] |
| − | local deviceId = r:value(2)
| |
| − | c8y:send('108,'..deviceId..',SUCCESSFUL')
| |
| − | sys.exec("reboot")
| |
| − | end
| |
| | | | |
| − | function init()
| + | After successful device registration, there is one more thing that you need to do in order to start monitoring your equipment. Find your router at '''All devices''' page. Then simply press the name of the item and you will be forwarded to the info window. |
| − | srInfo('*** Stream Init ***')
| |
| − | -- set device name and type
| |
| − | c8y:send('103,'..c8y.ID..','..DEVICE_NAME..','..DEVICE_TYPE)
| |
| − | -- set restart as supported operation
| |
| − | c8y:send('107,'..c8y.ID..',c8y_Restart')
| |
| − | -- set imei, cellid and iccid first time
| |
| − | mobileDataStream()
| |
| − | -- create timer which will stream mobile info data
| |
| − | local m_timer = c8y:addTimer(10 * 1000, 'mobileDataStream')
| |
| − | m_timer:start()
| |
| − | -- register restart handler
| |
| − | c8y:addMsgHandler(502, 'restart')
| |
| − | return 0
| |
| − | end
| |
| | | | |
| − | function mobileDataStream()
| + | [[Image:Cloud of things adding device 9.png]] |
| − | local imei = utl.trim(sys.exec("gsmctl -i"))
| |
| − | local cell = utl.trim(sys.exec("gsmctl -C"))
| |
| − | local icc = utl.trim(sys.exec("gsmctl -J"))
| |
| − | local type = utl.trim(sys.exec("gsmctl -t"))
| |
| − | local oper = utl.trim(sys.exec("gsmctl -o"))
| |
| − | local sign = utl.trim(sys.exec("gsmctl -q"))..' dBm'
| |
| − | local req = '105,'..c8y.ID
| |
| − | req = req..','..imei
| |
| − | req = req..','..cell
| |
| − | req = req..','..icc
| |
| − | req = req..','..type
| |
| − | req = req..','..oper
| |
| − | req = req..','..sign
| |
| − | -- send mobile info
| |
| − | c8y:send(req)
| |
| − | local wantype = utl.trim(sys.exec("uci get -q network.wan.ifname"))
| |
| − | local wanip = utl.trim(sys.exec("curl -s http://whatismyip.akamai.com"))
| |
| − | -- send wan info
| |
| − | c8y:send('106,'..c8y.ID..','..wanip..','..wantype)
| |
| − | end
| |
| | | | |
| | + | Here you will need to set the '''Required interval'''. This parameter defines how often you expect to hear from the device. If, for example, you set the required interval to 60, you expect the device at least to communicate once in an hour with Cloud of Things. RUT device sends data to the server every 10sec. |
| | | | |
| − | Once application finds lua script, it will call „init“ function. This is where all initialization of timers and other stuff should be.
| + | [[Image:Cloud of things monitoring device 1.png]] |
| | | | |
| − | Sending information is quite simple:
| + | If everything was done correctly you should now be able to monitoring your device on Cloud of Things. For more information about this platform visit this website: https://iot.telekom.com/en/platform |
| − | | |
| − | c8y:send('103,'..c8y.ID..','..DEVICE_NAME..','..DEVICE_TYPE)
| |
| − | | |
| − | By using „c8y:send“ function, first string contains request code, which was defined in the template, earlier. Then comma must appear after each value. The above line shows how we update device name and device type with our own.
| |
| − | | |
| − | For more information about Lua API, download Cumulocity C++ SDK: https://bitbucket.org/m2m/cumulocity-sdk-c/downloads and look up inside „sdk/doc/lua.html“ with a browser. | |
| | | | |
| | ==External Links== | | ==External Links== |
| − | https://www.cumulocity.com/try-for-free
| |
| − |
| |
| − | https://www.cumulocity.com/guides/reference/smartrest
| |
| | | | |
| − | https://bitbucket.org/m2m/cumulocity-sdk-c/downloads | + | https://iot.telekom.com/en/platform |
| | | | |
| | {{Template: trademark disclaimer}} | | {{Template: trademark disclaimer}} |