Searching...

Matching results

    How to use the Data Push Connector

    Integrate and extend your AirVantage platform

    This topic provides an overview of what you can do with the AirVantage Cloud Connector via a simple use case: getting raw data from your system and sending it to an MQTT topic.

    We’ll explain all the technical aspects needed for a robust, secure, and reliable interface:

    • Principles and best practices
    • Configuration and authentication
    • How to get messages

    1 / Principles

    2 / Configuration

    3 / Get messages

    Principles

    This section explains why to use the Cloud connector, what it is, and the available options.

    Introduction

    The Cloud Connector is an AMQP queue mechanism that provides the following:

    • Notifications from AirVantage for a new message, without polling the server
    • Routing mechanism
    • Robust messaging for applications
    • High volume of messages
    • Runs on all major operating systems
    • Open source libraries for several common languages (Java, c#, python, PHP, etc.)

    Parameters

    When setting up a queue on AirVantage, you have to define the notifications you want: operations, data, alert, or usages.

    You can then filter the data to send it to one of several queues.

    For example, if you want to send data for your internal application and for a partner application, you can send all of your data to your internal application (default) and filter to send non-confidential data to your partner.

    Reliability

    Have a look at this page on reliability. It explains how messages are stacked on the producer side (AirVantage) if no consumer receives the messages.

    If there is no acknowledgment, the message is sent after a delay.

    Don’t use a cron task to reinitialize your connection, as it is not efficient.

    Configuration

    This section explains how to configure your client to be robust, reliable, and secure. It is the most important section in this page.

    Which tool can be used?

    • RabbitMQ can be used to start without the AirVantage queue.

    AMQP Queue creation

    Supply the following information using the CRM and select Request Support:

    • Company name
    • AirVantage server (EU only); You can identify the server from the URL (eu.airvantage.net).
    • IP addresses to white list which clients can connect to the AMQP server.
    • Type of messages you want to receive:
      • Alert event: Any alert rule triggered will be sent.
      • Operation: Any operation state will be sent (creation, progress, success, or failed)
      • Usages: Any SIM usage.
      • New message sent by the device: Any incoming device communication.
        • Optionally, you can supply the data path to whitelist the data (only the values for this data will be sent in the data stream). To get the data path for data, navigate to the timeline to view the data path in the tooltip as shown in the screenshot below:

    In all the cases, SSL is enabled.

    You can use your own AMQP server by supplying the following information as well:

    • AMQP hostname
    • username
    • password
    • vhost
    • port
    • queue name

    Current connector limitations:

    • Uses the default exchange “”, with the queue name as the routing key.
    • vhost must start with “/”.
    • Only connects with TLS v1.2.

    How do I configure the setup?

    When subscribing to the Cloud Connector option, Sierra Wireless will supply these parameters:

    • Host is push.eu.airvantage.net
    • VirtualHost
    • Username
    • Password
    • Port: 5671 (for a SSL connection)
    • QueueName

    You have to use the following parameters when instantiating the factory to create your queue consumer:

    • RequestedHeartbeat to 30s
    • ssl on
    • AutomaticRecoveryEnabled = true
    • TopologyRecoveryEnabled = false
    • NetworkRecoveryInterval = 10s;

    Acknowledgments with stale delivery tags will not be sent. Applications that use manual acknowledgments and automatic recovery must be capable of handling redeliveries.

    Get the messages

    This section explains how to consume a high load of messages from the server.

    Initialize the consumer

    AMQP consumer prefetch setting

    The prefetch value specifies how many messages are sent to the consumer at the same time. It is used to get as much out of your consumers as possible.

    The default prefetch setting gives clients an unlimited buffer, meaning that the server, by default, sends as many messages as it can to any consumer that looks ready to accept them.

    Messages that are sent are cached by the client library (in the consumer) until they have been processed.

    Prefetch limits how many messages the client can receive before acknowledging a message.

    A typical mistake is to have an unlimited prefetch (default setting), where one client receives all messages and runs out of memory and crashes, and then all messages are re-delivered again.

    Of course, caching messages on the consumer side has repercussions.

    All pre-fetched messages are removed from the queue and become invisible to other consumers. Therefore, setting the prefetch count to a high value will skew message distribution between different consumers. Too small of a prefetch count, on the other hand, may hurt performance since the server is waiting to get permission to send more messages most of the time.

    • If you have a single consumer or a few consumers processing messages quickly, we recommend prefetching many messages at once (e.g., anything between 30 and 50).
    • If you have many consumers, and a short processing time, we recommend a lower prefetch value (e.g. anything between 20 and 30).
    • If you have many consumers, and/or a long processing time, we recommend you to set prefetch count to 1 so that messages are evenly distributed amongst all of your workers.
    model.BasicQos(0, 50, false);

    For more details :

    Connect to the queue: acknowledgment

    BasicConsume(queueName, noAck, consumer)

    Why not use auto-acknowledgment? If for any reason, the data is not correctly processed on the consumer side and the message is lost (e.g., from an application reboot), the message and its content will be indefinitely lost. If you use manual acknowledgment, AirVantage will be able to send it again after the reconnection, while the message content has not been processed, stored, and then acknowledged.

    Get the messages

    See Message Format section for a description of the message format.

    You must support both message formats because you may receive messages in either format.

    Sample code

    AMQP2MQTT : This Java sample reads from the data push connector to a MQTT topic and is structured to show you the best practices. For AMQP, have a look at / src / main / java / amqptomqttadapter / amqp:

    • AmqpConnectionManagerImpl: Everything needed to create, manage a connection, and configure a ShutdownListener to be notified when the connection is down.
    • MessageListenerImpl: Your code to handle messages from AirVantage. Most of this class can be reused for your own application (two lines are specific for this sample with MQTT).
    • AmqpConfiguration: Contains the AMQP connection configuration.
    TOP