AGG (AggreGate) Library

Top  Previous  Next

The AGG library implements an interface to Tibbo AggreGate Server (http://aggregate.tibbo.com). It is the "agent" that runs on your Tibbo BASIC/C device and connects it to the server using Tibbo's proprietary AggreGate Communication Protocol, or ACP (http://aggregate.tibbo.com/docs/ap_protocol.htm). Among the six ways to connect a device to the AggreGate server (http://aggregate.tibbo.com/technology/connectivity.html), using the library fast-tracks you through either the "second way" or the "fourth way".

The second way — "Connecting An Existing Device With AggreGate Agent" — assumes that there is a "legacy" device which is already designed, and possibly in production. This device knows nothing about Tibbo's AggreGate technology, yet you want to connect it to the AggreGate server. In order to achieve this, you use a Tibbo BASIC/C module or controller (EM1000, DS1206, etc.) to act as an "adaptor" that translates between the native protocol (or signals) of the legacy device and the AggreGate server. The fastest way to get this done is to write a Tibbo BASIC/C application that relies on the AGG library for the ACP implementation.

The fourth way — "Designing A New Device Based On Programmable Module" — is for when you are building a new device from scratch and you want this device to work with AggreGate. You take one of our very capable modules (such as the EM1000) and use it as the "CPU" of the new device. You then task this "CPU" with all kinds of things that make your device operational. One of the tasks — communicating with the AggreGate server — is handled by the AGG library.

The AggreGate Communication Protocol (ACP) is rather complex and would take you quite some time to read through, comprehend, and implement — have you not had the AGG library. When you are using the library, all this complexity is hidden behind an easy-to-use configurator. Fill in all the necessary "items", and the server will know how to work with your device.  

Without resorting to rewriting the AggreGate manual (http://aggregate.tibbo.com/docs/), let's remind ourselves that from the AggreGate's point of view, your device is an "object" which comprises items of three kinds: variables (properties), functions (methods), and events. To avoid confusion with the internal variables, methods, and events of Tibbo BASIC/C, we will refer to AggreGate ones as A-variables, A-functions, and A-events.

An A-variable can be a simple single-value affair, an array of values, or a full-blown data table (and it will still be a "variable" in the AggreGate's view). The AGG library relies on the STG (settings) library for storing single-value and array A-variables. This provides for persistent and reliable storage of A-variables, and also — through pre-gets and post-sets — for controlling and monitoring the device operation through A-variables (settings). Naturally, the latter will require the custom code to be written and placed into callback_stg_pre_get() and callback_stg_post_set().

Table A-variables are handled through the TBL (tables) library [not yet documented].

A-functions and A-events require custom code to be written, so it's not enough to just put necessary data into the configurator.

 

Library Info

Supported platforms:

Any platform. If the platform of your choice doesn't support the RTC you will have to implement date/time-keeping in your own way (for example, by connecting an external RTC chip and writing necessary code).

Files to include:

aggregate.tbs, aggregate.tbh (from current_library_set\aggregate\trunk\).

Dependencies:

SOCK library;

TIME library [not yet documented];

WLN library if your application will be connecting to the AggreGate server through Wi-Fi;

GPRS library if your application will be connecting to the AggreGate server through GPRS.

API procedures:

Use API procedures to interact with the library.

agg_start() — starts the AGG library, parses the configuration file, prepares all necessary variables.

agg_stop() — stops the AGG library causing it to release occupied buffers.

agg_get_connection_state() — gets the current state of the connection to the AggreGate server

agg_record_decode() — extracts the value of the specified argument from the encoded string containing the values of all arguments for an A-function.

agg_record_encode() — appends the argument's value to the encoded A-function's argument string in preparation for sending this string to the AggreGate server.

agg_fire_instant_event() — generates an A-event and sends it to the AggreGate server without storing it into the log.

agg_stored_event_added() — must be called every time a stored A-event is added to the log file.

agg_proc_stored_events() — nudges the AGG library to process stored A-events.

Event procedures:

agg_proc_timer() — call this from the on_sys_timer() event handler.

agg_proc_data() — call this from the on_sock_data_arrival() event handler.

agg_proc_data_sent() — call this from the on_sock_data_sent() event handler.

agg_proc_sock_event() — call this from the on_sock_event() event handler.

Callback procedures:

Implement the bodies of callback procedures elsewhere in your project.

callback_agg_get_firmware_version() — requests the version string for the current application.

callback_agg_device_function() invoked when the device needs to execute an A-function.

callback_agg_synchronized() — informs of the completion of the synchronization process between the device and the AggreGate server.

callback_agg_pre_buffrq() — called when the library needs to allocate buffer space and the required space is not available.

callback_agg_buff_released() — called when the library no longer needs buffers and released them.

callback_agg_error() — informs of an error or condition detected within the library.

callback_agg_convert_setting() — invoked every time an A-variable is being read or written. Provides an opportunity to change the value or type before writing to a setting or after reading from a setting.

callback_agg_convert_event_field() — invoked every time a stored A-event is being extracted from the log and sent to the server. Provides an opportunity to change the value or type of A-event arguments before sending the stored A-event to the server.

callback_agg_rtc_sg() —  invoked when the library needs to get or set the device's date and time. Necessary only when "use custom RTC" option is selected in the configurator.

Required buffer space:

4 buffer pages