cancel
Showing results for 
Search instead for 
Did you mean: 
cancel
Showing results for 
Search instead for 
Did you mean: 

Getting started with Axeda AMMP

Highlighted
Amethyst

Getting started with Axeda AMMP

The past few years has seen a tremendous explosion in the numbers of devices with Internet connectivity, and the Axeda product has continued to evolve to meet the requirements of these devices, which are often memory and CPU constrained.  Beginning with the Axeda Platform 6.6 release, the Axeda Adaptive Machine Messaging Protocol (AMMP) has been available that allows any device that can make an HTTP GET/POST request to send data to the Axeda Machine Cloud.  AMMP uses standard, JSON messages sent inside HTTP requests.

How to get AMMP

AMMP is a separately available product that can be added to an Axeda installation.  Customers should discuss with their Account Managers to get access to the Axeda AMMP product offering.  AMMP is a device codec that requires the installation of the Axeda AnyDevice Codec Server (ACS) component.  This configuration presents a new endpoint for customer installations - an https://example.axeda.com instance will have an ACS instance available at https://example-connect.axeda.com.  Self-hosted customers can create their own hosting/URL infrastructure, but this is the default available to Axeda On-Demand Center customers.

How to set up assets to talk AMMP

Before you can start deploying devices to talk AMMP to an Axeda instance, a Model Communication Profile must be created for any Model that is expected to communicate with the AMMP protocol.  This is required in order to configure the proper egress mechanism so that the device can get access to messages waiting for it on the Axeda Platform.​  Attached to this document is a file called ​​AMMP_CreateCommProfile.groovy.zip​. ​ This file contains a Groovy-based script that is copied into the Platform as a Custom Object, and then executed via Scripto - this is needed to be run for each device Model that requires access via AMMP.

​First Requests

Since all requests are via HTTP, it is useful to acquire a client that can perform REST API requests.  One highly recommended client is Postman (available in Chrome and standalone versions).

The first time a device connects to the Axeda Machine Cloud it should send a registration message.  A registration message must contain a model and serial number and can optionally include a ping rate.  The ping rate is how often the server should expect to hear from the device. The server will mark a device as off-line if it does not get a message before a configurable number ping times pass.  A device should also send a registration message whenever it powers up.

Using Postman, select POST  from the drop down next to the URL.  Enter the URL as shown below to register a new device.

https://example-connect.axeda.com/ammp/assets/1​ (Customers should use their own instances in the following examples)

Click ​Headers​ to add a header named 'Content-Type' with value of 'application/json':

Click the Body button and enter the line below.  The "mn" field below should be an already registered and configured model.

{  "id": { "mn" : "ExampleModel", "sn" : "ExampleDevice-001", "tn" : 0  },  "pingRate": 60  }

    

Click the Send button - an HTTP 200 OK response should be the expected result.  Logging into the platform and searching for ​'ExampleDevice-001' should show that it is registered

Now that a device has been registered is is now possible to send live information to the Axeda Machine Cloud.

Sending information is also done with a POST to a URL.  Instead of the asset's resource, we will be sending to the data resource.  Using Postman, the HTTP POST request will be structured like follows:

http://example-connect.axeda.com/ammp/data/1/ExampleModel!ExampleDevice-001

Change the body as follows:

{"alarms":[{"name":"over_temp","description":"freezer hot" }]}

    

Click on the 'Send' button and after the response returns, the alarm can be seen in the Asset Status Page in the Axeda Machine Cloud.

Four different types of information can be sent to the data resource and any or all can be included in one POST message.  All four types can have an optional time and priority field. If no time is specified, the time on the server at arrival will be added.

Alarm

Field Name

Purpose

Expected Data Type

Required?

Format, Range

Default Value

Default Behavior

name

Identify the alarm

String

Yes

Length: 0 <= N <= ?

Valid String Characters

description

Describe the alarm

String

No

Length: 0 <= N <= ?

None

severity

Describe the severity

Integer

No

Range: 0 <= N <= 1000

0

cause

Identify the cause

String

No

Length: 0 <= N <= ?

None

reason

Describe the cause

String

No

Length: 0 <= N <= ?

None

time

Time when the alarm occurred

No

ISO-8601 or Unix Epoch

None

Use server time if <Default Value>

priority

How much priority the server should give to processing

No

1 <= N <= 100

1

Alarm Example JSON


{

    "alarms": [

        {

            "name": "RadiationLeak",

            "description": "A radiation leak has been detected",

            "severity": 1000,

            "cause": "CoolantPipeBurst",

            "reason": "The main coolant pipe exploded",

            "time": 1364443200000,

            "priority": 100

        }

    ]

}

    

Once alarms reach the Axeda Machine Cloud, they will be in the "Started" state.  Once an alarm is received, it can be "Acknowledged", "Escalated", or "Closed".

Event

Field Name

Purpose

Expected Data Type

Required?

Format, Range

Default Value

Default Behavior

name

Identify the event

String

Yes

Length: 0 <= N <=?

Valid String Characters

description

Describe the event

String

No

Length: 0 <= N <= ?

None

time

Time when the event  occurred

Integer (Epoch Timestamp)

String (ISO-8601)

No

ISO-8601 or Unix Epoch

None

Use server time if <Default Value>

priority

How much priority the server should give to processing

Integer

No

1 <= N <= 100

1

Event Example JSON

{

    "events": [

        {

            "name": "RadiationLeak",

            "description": "A radiation leak has been detected",

            "time": 1364443200000,

            "priority": 100

        }

    ]

}

    

Mobile Location

Field Name

Purpose

Expected Data Type

Required?

Format, Range

Default Value

Default Behavior

latitude

Latitude

Float

Yes

-90 <= N <= +90

longitude

Longitude

Float

Yes

-180 <= N <= +180

altitude

Altitude/Elevation

Float

No

Unbounded

time

Time when the event occurred

Integer (Epoch Timestamp)

String (ISO-8601 Timestamp)

No

ISO-8601 or Unix Epoch

None

Use server time if <Default Value>

priority

How much priority the server should give to processing

Integer

No

1 <= N <= 100

1

Location Example JSON

{

    "locations": [

        {

            "latitude": 42.034061,

            "longitude": -71.237472,

            "altitude": 0.0,

            "time": 1364443200000,

            "priority": 100

        }

    ]

}

    

Note: The platform records the history of all the mobile locations a device has reported.  This has implications for the positions displayed in the Asset Status Map Charting components.

Data Item Set

Field Name

Purpose

Expected Data Type

Required?

Format, Range

Default Value

Default Behavior

dataItems

A collection of key/value pairs

Object<String, JSON Type>

Yes

Unbounded

time

Time when the data items were sampled

Integer (Epoch Timestamp)

String (ISO-8601 Timestamp)

No

ISO-8601 or Unix Epoch

None

Use server time if <Default Value>

priority

How much priority the server should give to processing

Integer

No

1 <= N <= 100

1

Data Item Set Example JSON

{ "data" :[

  {

    "dataItems": {

      "CurrentSong": "Comfortably Numb",

      "PreviousSong": "Rain When I Die",

      "NextSong": "Whole Lotta Love",

      "FreeMemory": 1237.24,

      "DebugModeEnabled": true

    },

    "time": 1364443200000, "priority": 100

  },

  { "dataItems":{

      "bar":"camp",

      "pot1":23.3

    },

    "time": 1364443234000, "priority": 100 }

]}

    


Data Items are sent as sets that share a common recording time and priority.  Data Item values follow JSON representation standards and can be: string, numeric, or Boolean.

Below is an example message showing all four information types that can be sent:

{

  "alarms": [

        {

            "name": "RadiationLeak",

            "description": "A radiation leak has been detected",

            "time": 1364443200000

        }

    ],

    "events": [

        {

            "name": "Foo",

            "description": "A Foo occurred"

        }

    ],

    "data":[

        {

            "dataItems":{

              "bar":"camp",

              "pot1":23.3},

            "time": 1364443200000

        }

    ],

    "locations": [

        {

            "latitude": 32.00,

            "longitude": -78.00

    }

    ]

}

    

Polling

​Axeda AMMP is designed to provide a minimalist communication protocol between devices.  As such each request has egress items returned in the HTTP response body, no matter the type of data sent as the request body.  This is so that extra requests to retrieve egress do not have to be made.  But if a device has no updates to make, it is still able to make periodic polling requests to the Codec Server to get any egress items available to it.

This request is simply a REST request of HTTP POST to the example URL: https://example-connect.axeda.com/ammp/assets/1/ExampleModel!ExampleDevice-001​with an empty request body.


Next steps and caveats

Keep in mind that egress data can be returned in ANY HTTP response body.  If a device has a programming error or a power failure occurs before the request is processed, then it is possible that request can be lost - permanently.  The Axeda Platform does not replay egress items once it has been delivered to the device.  Additional logical facilities are available on the Axeda Platform to be able to provide replay/retry communications to the device.

Bibliography

Using Axeda Scripto

Axeda AMMP Technical Reference (1.2.0 Dec 2014)