Searching...

Matching results

    How to use the Data Push Connector

    Integrate and extend your AirVantage platform

    Here we give you an overview of what you can do with the AirVantage Cloud Connector via a simple use case: getting raw data from your system, then send them to a MQTT topic.

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

    • principles & best practices
    • configuration & authentication
    • how to 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 which allows:

    • to be notified 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, …)

    Parameters

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

    According the data, you can filter the data to send them in one of several queues.

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

    Reliability

    Have a look to this page about reliability and which explains how messages are stacked on the producer side (AirVantage) if no consumer gets the messages.

    If no acknowledgement, 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 see what is the server in the url (eu.airvantage.net).
    • IP Addresses in order to white list the clients which can connect to the AMQP server.
    • Kind of messages you want to receive:
      • Alert event: any alert rule triggered will be send
      • Operation: any operation state will be sent (creation, progress, success or failed)
      • Usages: any SIM usage
      • New message sent by the device: any device incoming communication
        • Optionnaly you can supply the data path to whitelist the data (only the values for these data will be sent in the data stream). To get the data path for a data, you can go to the timeline to view the data path in the tooltip like in the screenshot below:

    In all the cases, SSL is enabled.

    You can require to use your own AMQP server. In this case, you have to supply these information as well:

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

    Current connector limitations:

    • use default exchange “”, with queue name as routing key
    • vhost should start with “/”
    • only connect with TLSv1.2

    How can I configure?

    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 creating the factory to create your queue consumer:

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

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

    Get the messages

    This section explains you how to consume the messages from the server in order to support a high load of messages.

    Initialize the consumer

    AMQP consumer prefetch setting

    The prefetch value is used to specify 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.

    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 it has 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. Hence setting prefetch count to a high value will skew message distribution between different consumers. A too small prefetch count, on the other hand, may hurt performance since the server is most of the time waiting to get permission to send more messages.

    • If you have one single or 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 than for one single or few consumers (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 among all your workers.
    model.BasicQos(0, 50, false);
    

    For more details :

    Connect to the queue: acknowledgement

    BasicConsume(queueName, noAck, consumer)
    

    Why don’t you use auto-acknowledgment? because if for any reason, the data is not correctly processed on the consumer side and the message is lost (application reboot), this message and its content will be definitively lost. If you use manual acknowledge, until the message content is not processed and stored adn then acknowledged, AirVantage will be able to send it again after the reconnection.

    Get the messages

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

    Both two formats must be supported because you can receive messages with the two formats.

    Sample code

    AMQP2MQTT : This java sample read whatever comes from the data push connector to a MQTT topic. It is structurated to show you the best practices. About AMQP, have a look to / src / main / java / amqptomqttadapter / amqp:

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