AMCI Satellite Transceiver

AMCI's Website

• • To view information from AMCI's website or to verify information obtained from XML sent from AMCI, click here and enter your Credentials.

AMCI XML Documentation

An individual Asset or Site in SatAlarm collects discrete data into one or more Channels.

There are two types of Channels: Normal Numbered Channels and Non-Channels.

Normal Numbered Channels

• • Have an assigned channel number from 0 through 999

  • Have a user-defined description

  • Have a component selected from a pre-defined list of components

  • Have an alarm state (Normal, Warning, or Alarm)

  • Can use formulas to convert incoming or raw value

  • Have both a raw and converted unit of measure

  • Can generate notifications

  • Are displayed on the Asset Details Page in SatAlarm

  • Can be graphed

Non-Channels

• • Have none of the above Normal Numbered Channel characteristics

  • Only have a name, value, and possibly a description

Each Channel, regardless of type, has a unique channel identifier known as an Input Type Id. The unique channel identifier has a description.

In the XML you are receiving from the SatAlarm Portal, an <IncomingMessage> element represents an individual message for a given Site. Inside of the <IncomingMessage> element is one or more <Value>elements, each of which describes the state of an individual Channel.

The attributes inside of the <Value> element are as follows:

• • Id – The unique channel identifier (Input Type Id)

  • Name – For Normal Numbered Channels this is the user-defined Channel description. For Non-Channels this is the description of the unique channel identifier (Input Type Id)

  • AltName – The channel number (Normal Numbered Channels only)

  • RawValue – The reported value for the Channel

  • Value – The converted value for the Channel. This value may be different from the RawValue if this is a Normal Numbered Channel that is using a formula. The Value and the RawValue will always be the same for Non-Channels

  • AlarmState – N(ormal), W(arning), or A(larm) (Normal Numbered Channels only)

  • ValueDescription – Usually a description of what the new value means (Normal Numbered Channels only)

  • RawUnitOfMeasure – Unit of measure description for the RawValue (Normal Numbered Channels only)

  • UnitOfMeasure – Unit of measure description for the Value (Normal Numbered Channels only)

  • TriggerState – A description of the transition from the previous value of this Channel to the current value (Normal Numbered Channels only)

SatAlarm Portal 2.0 Overview

Introduction

• The SatAlarm Portal is a bi-directional XML gateway used to exchange information between SatAlarm Server and external clients. A publish/subscribe arrangement is used to send asynchronous information from SatAlarm to its clients and a simpler request/response arrangement for client to SatAlarm messages.

XML Document Description and Samples

• DTD files describing the XML documents used by the SatAlarm Portal as well as XML example files are available on the SatAlarm Wiki site http://wiki.satalarm.com.

Portal Publisher

• On the publish/subscribe side, the Portal has a list of subscribers that it manages. Whenever one or more messages are received in SatAlarm from remote assets in the field, the Portal will create a <SubscriberIssue> XML document and send it to a URL configured for the subscriber. The XML document is sent using an HTTP POST. The subscriber must respond to the Portal with an <AMCiResponse> XML document to confirm the delivery. If the delivery fails, the Portal will try again later. This means that messages will never be lost due to communications failure.

• The contents of the <SubscriberIssue> are anywhere from one to 32 messages received from the assets in the field. You will only receive messages for assets within your purview. Look at the <SubscriberIssue> example files for an idea of the information that you can expect.

Portal Requests

• On the request/response side, the Portal has the ability to accept requests from the subscribers. There are two types of requests: configuration requests and outgoing message requests. Both types of requests are contained in an <AMCiRequest> XML document.

• Configuration requests ask for a description of all of the assets that the subscriber controls. The request will return an <AMCiResponse> XML document containing information such as the name, serial number, and description of each asset.

• Outgoing message requests are sent to the Portal to forward messages to the assets in the field. Typical requests include polling an asset, sending a digital pulse, and sending a short text message. The request will return an <AMCiResponse> XML document indicating success or failure.

• For security purposes, all requests must be preceded by an <AMCiLogin> XML document. The <AMCiLogin> document contains a user and password for request validation. This arrangement implies that two separate XML documents are sent in a single HTTP POST when making a request.

SatAlarm Portal 2.0 Enhancements

• The primary new feature is a new type of Subscriber Issue that our subscribers can receive. The previous version of the SatAlarm Portal would package up the raw information that we receive from the GlobalWave assets in a <SubscriberIssue> XML document. This arrangement worked well for some of our clients who wanted information about the native analog and digital ports on the GlobalWave terminals or had created their own messaging applications.

• With the advent of the new GlobalWave and AMCi packages that support Modbus communication, the limitations of the <SubscriberIssue> document have been exposed. Most of the Modbus messaging is contained in 11-byte Terminal Short Messages, which is sent unparsed in the <SubscriberIssue> document. The parsing rule for the messages can be quite complex, and requiring our customer to do this really was impractical and quite unacceptable.

• SatAlarm Portal 2.0 now allows a second type of Subscriber issue that is contained in the <SubscriberIssue2> document. The <SubscriberIssue2> document contains all of the information after SatAlarm Server has completed all of the parsing and conversions that are normally performed on the raw incoming messages.

• The format of the new Subscriber issue is more normalized and therefore more conducive to being used by back-end applications.

Future Enhancements

• Message Stitching – Since the communications pipe for GlobalWave is limited to 11 byte messages, the field units often send multiple messages in response to a single event. Currently, the Portal will send a separate <IncomingMessage> element for each message. The new Message Stitching feature will gather multiple related messages and merge them into a single <IncomingMessage> element.

• Portal Mailbox – The publishing arrangement whereby the Portal pushes out Subscriber issues as soon as SatAlarm Server receives incoming messages provides a timely delivery of messages. Unfortunately, we are starting to see more customer sites that can not incoming traffic due to security, firewall, and IT Services objections. To address this problem, we are proposing an enhancement to the SatAlarm Portal that would allow Subscribers to connect to the Portal and request new Subscriber issues instead of the Portal automatically publishing the information as it arrives.

• Standardized Subscriber Adaptors - If we find any widely used back-end applications that use an XML data feed, we can possibly create standardized adaptors for the Portal that allows us to communicate with those applications without requiring the customer to write any custom software on their side.

• Modbus TCP – We are exploring the possibility of exposing the Modbus data that we collect using Modbus TCP.

Conclusion

• • The SatAlarm Portal is up and running with a number external and internal subscribers. We are continuing to refine and improve the application as we receive feedback from our users. If you have any questions or requests, please contact us.