Difference between revisions of "Phonebot developer's reference/Object reference/Using Phonebot services"

From EtherWiki
Jump to: navigation, search
(Object reference)
Line 14: Line 14:
  
 
== Object reference ==
 
== Object reference ==
 +
 +
 +
Properties
 +
 +
{|class="wikitable sortable"
 +
|-
 +
!Syntax
 +
!Description
 +
|-
 +
|<code>auto_start</code>
 +
|Read-only.
 +
|-
 +
|<code>event_size</code>
 +
|Read-only. The number of events in the queue. When monitoring multiple services, this property can be used in <code>on_service</code> events to determine which service was updated.
 +
|-
 +
|<code>name</code>
 +
|Read-only.
 +
|-
 +
|<code>text</code>
 +
|Read-only.
 +
|-
 +
|}
 +
 +
Methods
 +
 +
{|class="wikitable sortable"
 +
|-
 +
!Syntax
 +
!Description
 +
|-
 +
|<code>size = clear_events()</code>
 +
|Delete all events and return how many were deleted.
 +
|-
 +
|<code>event = get_event()</code>
 +
|Retrieve the next event in the queue.
 +
|-
 +
|<code>value = get_property(name)</code>
 +
|Retrieve a service property.
 +
|-
 +
|<code>event = pop_event()</code>
 +
|Retrieve and delete the next event in the queue.
 +
|-
 +
|<code>set_property(name, value)</code>
 +
|Set a service property.
 +
|-
 +
|<code>start()</code>
 +
|Start the service.
 +
|-
 +
|<code>stop()</code>
 +
|Stop the service.
 +
|-
 +
|}
 +
 +
Events
 +
 +
{|class="wikitable sortable"
 +
|-
 +
!Syntax
 +
!Description
 +
|-
 +
|<code>on_service</code>
 +
|
 +
|-
 +
|}
 +
 +
In addition to the common properties, methods, and events, each service may have custom properties:
  
 
{|class="wikitable sortable"
 
{|class="wikitable sortable"
Line 36: Line 102:
 
|}
 
|}
  
Events can be manipulated in the following manner:
+
Events can be accessed and parsed in the following manner:
  
 
HTTP:
 
HTTP:
Line 59: Line 125:
 
  event = event:datetime.format("HH:mm:ss")
 
  event = event:datetime.format("HH:mm:ss")
  
Sensor types:
+
The sensor service can be configured to return any combination of sensor types. Each type has its own name and data format as described below:
  
 
{|class="wikitable sortable"
 
{|class="wikitable sortable"
Line 119: Line 185:
  
 
--[http://developer.android.com/reference/android/hardware/SensorEvent.html#values SensorEvent values]
 
--[http://developer.android.com/reference/android/hardware/SensorEvent.html#values SensorEvent values]
 
Properties
 
 
{|class="wikitable sortable"
 
|-
 
!Syntax
 
!Description
 
|-
 
|<code>auto_start</code>
 
|Read-only.
 
|-
 
|<code>event_size</code>
 
|Read-only. The number of events in the queue. When monitoring multiple services, this property can be used in <code>on_service</code> events to determine which service was updated.
 
|-
 
|<code>name</code>
 
|Read-only.
 
|-
 
|<code>text</code>
 
|Read-only.
 
|-
 
|}
 
 
Methods
 
 
{|class="wikitable sortable"
 
|-
 
!Syntax
 
!Description
 
|-
 
|<code>size = clear_events()</code>
 
|Delete all events and return how many were deleted.
 
|-
 
|<code>event = get_event()</code>
 
|Retrieve the next event in the queue.
 
|-
 
|<code>value = get_property(name)</code>
 
|Retrieve a service property.
 
|-
 
|<code>event = pop_event()</code>
 
|Retrieve and delete the next event in the queue.
 
|-
 
|<code>set_property(name, value)</code>
 
|Set a service property.
 
|-
 
|<code>start()</code>
 
|Start the service.
 
|-
 
|<code>stop()</code>
 
|Stop the service.
 
|-
 
|}
 
 
Events
 
 
{|class="wikitable sortable"
 
|-
 
!Syntax
 
!Description
 
|-
 
|<code>on_service</code>
 
|
 
|-
 
|}
 
  
 
[[Category:Phonebot]]
 
[[Category:Phonebot]]

Revision as of 23:35, 27 March 2012

Services are non-visual components that monitor different environment states and trigger an event when the state changes. The available services are:

  • http - Make web requests
  • sensor - Monitor hardware sensors
  • timer - Alert at specific intervals

When a service is updated, its OnUpdate event fires, then the application's OnService event fires, and finally the current module's OnService event fires.

Each Service stores its update data in a queue. The methods get_event() and pop_event() access the next event in the queue and event_size returns how many events exist.

The maximum number of sensor events that will be retained in the queue is controlled by the "Sensor buffer" Phonebot property. The "Sensor buffer" value, the sensor service's "Minimum update frequency" value, and the amount of script within each OnUpdate and OnService event will determine how responsive your application is when reading sensor data. If updates are sluggish, try reducing the buffer size.

Phonebot.service-lifecycle.png

Object reference

Properties

Syntax Description
auto_start Read-only.
event_size Read-only. The number of events in the queue. When monitoring multiple services, this property can be used in on_service events to determine which service was updated.
name Read-only.
text Read-only.

Methods

Syntax Description
size = clear_events() Delete all events and return how many were deleted.
event = get_event() Retrieve the next event in the queue.
value = get_property(name) Retrieve a service property.
event = pop_event() Retrieve and delete the next event in the queue.
set_property(name, value) Set a service property.
start() Start the service.
stop() Stop the service.

Events

Syntax Description
on_service

In addition to the common properties, methods, and events, each service may have custom properties:

Service Properties Description
http url Makes a GET request to a URL. Returns a single event in the queue containing the response.
sensor sensors - array of sensor names

update_frequency - time between updates in milliseconds

Monitors one or more hardware sensors. Returns an event containing a comma-delimited list of values beginning with the sensor name (e.g. orientation,60.0,-28.0,3.0). The range of each value is dependent on the sensor.
timer duration - time between updates, formatted as h:m:s, m:s, or s Fire the update events at regular intervals. The event will first fire immediately after the service is started. Returns an event containing the datetime value when the update happened.

Events can be accessed and parsed in the following manner:

HTTP:

event = http_service.pop_event()
// query with XPath
items = event:xml.query("//root/item")
// read json data
root = event:json.get_element("root")
items = event:json.get_element("item")

Sensor:

event = sensor_service.pop_event()
event = event:string.split(",")
name = event:array.get_element(0)
// get values from index 1 and greater

Timer:

event = timer_service.pop_event()
event = event:datetime.format("HH:mm:ss")

The sensor service can be configured to return any combination of sensor types. Each type has its own name and data format as described below:

Name Structure of event value

(actual values are prefixed with the name, i.e. name,value1,value2,...)

Description
accelerometer x,y,z Acceleration in meters/second^2
gps latitude,longitude,accuracy,altitude,bearing,speed
gravity x,y,z Gravity in meters/second^2
gyroscope x,y,z Angular speed in radian/second
light l Ambient light in lux units
linear_acceleration Acceleration in meters/second^2
magnetic_field x,y,z Magnetic field in micro-Teslas
orientation azimuth,pitch,roll Measured in degrees. 0=North, 90=East, 180=South, 270=West; -180..180; -90..90
pressure p Atmospheric pressure in millibars
proximity p Proximity in centimeters
rotation_vector
temperature

--SensorEvent values