====Python Live Data API====

This API allows you to create Python applications that utilise ARDI live data. 

===Usage Example===

<code>
from ardi.api.ardiapi as ardiapi

#Connnect to the ARDI server
ardi = ardiapi.Server("<ardiserverurl>","<ardisitename>")
if ardi.Connect() == False:
   sys.exit(0)

#Create a live-data session
sub = ardiapi.Session(ardi)
mychannel = sub.AddChannel('<asset name>','<property name>')

def ProcessNewValues(values):
    echo str(values)

sub.Callback(ProcessNewValues)
sub.Start()
sub.End()
</code>

===How It Works===

This is a quick breakdown of how the above example operates.

1) Create an **Server** object and connect it to the ARDI server.

<code>
ardi = ardiapi.Server("<ardiserverurl>","<ardisitename>")
if ardi.Connect() == False:
   sys.exit(0)
</code>

This loads all of the settings of your ARDI server, including the location of the consolidator.

2) Create an **Session** for live data, passing the Server we just created.

<code>
sub = ardiapi.Session(ardi)
</code>

This prepares the subscription by telling it the consolidator details. It does //not// connect to the server yet.

3) Add all of the data points you want to subscribe to.

<code>
mychannel = sub.AddChannel('<asset name>','<property name>')
</code>

You can add as many data points as you need.

The function returns a [[Channel|Channel]] object, which includes both the current value and some metadata about the point. 

There are also other mechanisms for subscribing to data points. You can use **AddChannels(aqlquery)** to add a number of different channels using an AQL query, or call **AddChannel** with only the one parameter to add properties via [[data points|data points]].

Finally, there is also the AddBulkChannels function which takes an array of point names in //asset//.//property// format (ie. **Main Oven.Temperature**). This function uses a dedicated lookup system in ARDI rather than sending many individual AQL queries, which is much faster when you want to add a large number of points to your subscription.

4) Define and Set the Callback Function

<code>
def ProcessNewValues(values):
    echo str(values)

sub.Callback(ProcessNewValues)
</code>

The callback function is invoked every time a value changes. Create the function (it can be a class member if you're implementing this in a class) and call **Callback** on the **Session**.

Note that the array returned in the parameter to ProcessNewValues contains only the [[Channel|channels]] that have changed since the last update - except for the first time the function is called, where it contains the value for every channel.

5) Start the Subscription

<code>
sub.Start()
</code>

Note that the **Connect** function is a //blocking// function - it will stop the code from proceeding.

If you'd like to continue with other tasks, we suggest running this function in a separate thread.

The subscription can be stopped with **sub.Stop()**.