Motion(Gyroscope and Accelerometer) Microservice Overview

A gyroscope is a device that uses Earth’s gravity to help determine orientation. An accelerometer is a compact device designed to measure non-gravitational acceleration. This page describes the Motion service and the available API's to get the gyroscope and accelerometer data.

### Motion Microservice ##

The Gyroscope and Accelerometer microservice, which is beta and supported on IR8xx platforms, in conjunction with NBI Gateway provides standard APIs over REST/WebSocket. The Gyroscope and Accelerometer values can be obtained in a request/response fashion using REST API or an application can simply open a web socket and receive streaming Gyroscope and Accelerometer data from the NBI gateway.

The Motion Microservice is available as a IOx installable and appears as below in the Microservice name-space.

[{id: "urn:cisco:system:service:protocolHandler:gyrscope", api-version: 1,version: "1.0.0"}]

An application should declare dependency on Gyroscope and Accelerometer service in its package.yaml before consuming Gyroscope and Accelerometer APIs. Once the dependency is declared, IOx hosting framework would ensure that Gyroscope and Accelerometer service is deployed before the application can be deployed on the IOx enabled device.

depends-on:
    packages:
      -
        name:  "IOxMotion"
        version: "1.5.0"

### Motion APIs ###

Motion micro service enquires the platform feature for Gyroscope and Accelerometer co-ordinates refresh, every time the REST invocation happens.

Gyroscope and Accelerometer microservice provides below REST API to enable Gyroscope and Accelerometer data streaming.

https://<router IP>:<NBI-Port>/api/v1/mw/motion/config
POST 
    {                
    "streaming-enabled": true 
    }

Motion microservice provides below REST API to retrieve the current Gyroscope and Accelerometer data.

https://<router IP>:<NBI-Port>/api/v1/mw/motion/gyroscope

{"G-X":"1907.50","G-Y":"-2152.50","G-Z":"6851.25","return-code":"200","timestamp":"2017:07:20:22:25:29.203156"}

https://<router IP>:<NBI-Port>/api/v1/mw/motion/accelerometer

{"XL-X":"-21.106","XL-Y":"-41.846","XL-Z":"1019.188","return-code":"200","timestamp":"2017:07:20:22:26:36.037110"}

Motion microservice provides below REST API to retrieve the current Gyroscope and Accelerometer Service configuration.

// https://<router IP>:<NBI-Port>/api/v1/mw/motion/config

{
  "value": {
    "streaming-enabled": true
  }
}

IOx Motion(Gyroscope and Accelerometer) Microservice Configuration

For the IOx Motion Microservice to provide Gyroscope and Accelerometer data over standard REST/Websocket APIs, below steps need to be performed

Install IOx Core Services on the router
Install IOx Gyroscope and Acceleromete Microservice

Core Services Installation

On IR8xx platforms, IOxCore is available as part of the image and hence there is no need for seperate installation In case a newer version of IOxCore is available, please follow below steps. Deploy the Core service bundle on the IR8xx device as below.

$ ioxclient svc install IOxCore iox-core-services-1.0.0.tar
Currently active profile :  211
Command Name: service-install
Installation Successful. Service is available at : https://10.78.106.211:8443/iox/api/v2/hosting/service-bundles/IOxCore
Successfully deployed

$ ioxclient svc act IOxCore --payload ~/act.json
Currently active profile :  211
Command Name: service-activate
Payload file : c:/act.json. Will pass it as application/json in request body..
Service IOxCore is Activated

$ ioxclient svc start IOxCore
Currently active profile :  211
Command Name: service-start
Service IOxCore is Started


$ ioxclient svc list
Currently active profile :  211
Command Name: service-list
List of installed Service :
 1. IOxCore    --->    RUNNING

$ cat ~/act.json
{
    "resources": {
        "network": [{"interface-name": "eth0", "network-name": "iox-nat0"}]
    }
}

NAT Configuration on IOS

NBI gateway and Message Broker may need access from outside the router for the applications to communicate with micro services APIs. Proper NAT rules need to be installed on the IOS for the NBI to be accessible.

Use IOXClient CLI to check the mapped port of the NBI and Broker. ioxclient svc info IOxCore

Add nat entries on the IOS to map the ports with the IP of the svcbr_0 of the Guest OS to the IP of the external interface or VLAN.

conf> ip nat inside source static tcp <svcbr_0 IP on GOS> 40000 interface GIGE-0 40000
ip nat inside source static tcp <svcbr_0 IP on GOS> 40001 interface GIGE-0 40001

### Motion(Gyroscope and Accelerometer) Service Installation ###

Deploy the Motion bundle in NAT mode on the IR8xx device as below.

$ ioxclient svc install IOxMotion iox-motion-service-1.0.0.tar
    Currently active profile :  211
    Command Name: service-install
    Installation Successful. Service is available at : https://10.78.106.211:8443/iox/api/v2/hosting/service-bundles/IOxMotion 
    Successfully deployed

    $ ioxclient svc act IOxMotion ~/act.json 
    Currently active profile :  211
    Command Name: service-activate
    Service IOxGPS is Activated

    $ cat ~/act.json
        {
        "resources": {
        "network": [{"interface-name": "eth0", "network-name": "iox-nat0"}],
        "devices": [{"type": "serial", "label": "MOTION_DEV", "device-id": "/dev/ttyS3"}]
    }

} $ ioxclient svc start IOxMotion Currently active profile : 211 Command Name: service-start Service IOxGPS is Started

    $ ioxclient svc list
    Currently active profile :  211
    Command Name: service-list
    List of installed Service : 
     1. IOxMotion     --->    RUNNING
     2. IOxCore    --->    RUNNING

Checking IOxMotion Data

Use the below REST URL to get the current location data.

https://<router IP>:<NBI-Port>/api/v1/mw/motion/gyroscope

GET

{"G-X":"1907.50","G-Y":"-2152.50","G-Z":"6851.25","return-code":"200","timestamp":"2017:07:20:22:25:29.203156"}

https://<router IP>:<NBI-Port>/api/v1/mw/motion/accelerometer

GET

{"XL-X":"-21.106","XL-Y":"-41.846","XL-Z":"1019.188","return-code":"200","timestamp":"2017:07:20:22:26:36.037110"}"timestamp": "1490007978"
}

Checking Streaming Motion(Gyroscope and Accelerometer) Data

Use the below WebSocket URL to get the current location data.

$ ioxclient svc infra msg ws  sub "motion"
Currently active profile :  motion
Command Name: service-infrastructure-messaging-websocket-subscribe
{"message":{"G-X":"2030.00","G-Y":"-43.75","G-Z":"6938.75","XL-X":"-20.435","XL-Y":"-42.883","XL-Z":"1016.199","return-code":"200","timestamp":"2017:07:20:23:02:01.070143"},"topic":"motion"}
{"message":{"G-X":"1855.00","G-Y":"-113.75","G-Z":"6860.00","XL-X":"-19.459","XL-Y":"-41.175","XL-Z":"1016.321","return-code":"200","timestamp":"2017:07:20:23:02:04.108064"},"topic":"motion"}
{"message":{"G-X":"1820.00","G-Y":"2231.25","G-Z":"6868.75","XL-X":"-19.581","XL-Y":"-40.626","XL-Z":"1017.297","return-code":"200","timestamp":"2017:07:20:23:02:07.146158"},"topic":"motion"}
{"message":{"G-X":"2135.00","G-Y":"2161.25","G-Z":"6860.00","XL-X":"-21.777","XL-Y":"-42.273","XL-Z":"1017.541","return-code":"200","timestamp":"2017:07:20:23:02:10.184141"},"topic":"motion"}
{"message":{"G-X":"2038.75","G-Y":"-78.75","G-Z":"6772.50","XL-X":"-18.605","XL-Y":"-41.724","XL-Z":"1017.724","return-code":"200","timestamp":"2017:07:20:23:02:13.222176"},"topic":"motion"}
{"message":{"G-X":"2021.25","G-Y":"-2222.50","G-Z":"6921.25","XL-X":"-18.361","XL-Y":"-42.212","XL-Z":"1002.352","return-code":"200","timestamp":"2017:07:20:23:02:16.259149"},"topic":"motion"}
{"message":{"G-X":"2021.25","G-Y":"-2196.25","G-Z":"6807.50","XL-X":"-20.191","XL-Y":"-41.785","XL-Z":"1016.626","return-code":"200","timestamp":"2017:07:20:23:02:19.297148"},"topic":"motion"}
{"message":{"G-X":"1916.25","G-Y":"2135.00","G-Z":"8890.00","XL-X":"-19.825","XL-Y":"-42.090","XL-Z":"1015.955","return-code":"200","timestamp":"2017:07:20:23:02:22.335152"},"topic":"motion"}

Next steps

Next Chapter - Modbus service