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

From EtherWiki
Jump to: navigation, search
Line 1: Line 1:
 +
Services are non-visual components that monitor different environment states and trigger an event when the state changes.
 +
 
[[Image:phonebot.service-lifecycle.png]]
 
[[Image:phonebot.service-lifecycle.png]]
 +
 +
== Object reference ==
 +
 +
{|class="wikitable sortable"
 +
|-
 +
!Service
 +
!Properties
 +
!Description
 +
|-
 +
|<code>http</code>
 +
|<code>url</code>
 +
|Makes a GET request to a URL. Returns a single event in the queue containing the response.
 +
|-
 +
|<code>sensor</code>
 +
|<code>sensors</code> - array of sensor names
 +
<code>update_frequency</code> - 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. <code>orientation,60.0,-28.0,3.0</code>). The range of each value is dependent on the sensor.
 +
|-
 +
|<code>timer</code>
 +
|<code>duration</code> - time between updates, formatted as <code>h:m:s</code>, <code>m:s</code>, or <code>s</code>
 +
|Fire the update events at regular intervals. The event will first fire immediately after the service is started. Returns an event containing the <code>datetime</code> value when the update happened.
 +
|-
 +
|}
 +
 +
Events can be manipulated 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")
 +
 +
Sensor types:
 +
 +
{|class="wikitable sortable"
 +
|-
 +
!Name
 +
!Structure of event value
 +
(actual values are prefixed with the name, i.e. <code>name,value1,value2,...</code>)
 +
!Description
 +
|-
 +
|<code>accelerometer</code>
 +
|<code>x,y,z</code>
 +
|Acceleration in meters/second^2
 +
|-
 +
|<code>gps</code>
 +
|<code>latitude,longitude,accuracy,altitude,bearing,speed</code>
 +
|
 +
|-
 +
|<code>gravity</code>
 +
|<code>x,y,z</code>
 +
|Gravity in meters/second^2
 +
|-
 +
|<code>gyroscope</code>
 +
|<code>x,y,z</code>
 +
|Angular speed in radian/second
 +
|-
 +
|<code>light</code>
 +
|<code>l</code>
 +
|Ambient light in [http://en.wikipedia.org/wiki/Lux lux units]
 +
|-
 +
|<code>linear_acceleration</code>
 +
|<code></code>
 +
|Acceleration in meters/second^2
 +
|-
 +
|<code>magnetic_field</code>
 +
|<code>x,y,z</code>
 +
|Magnetic field in [http://en.wikipedia.org/wiki/Tesla_(unit) micro-Teslas]
 +
|-
 +
|<code>orientation</code>
 +
|<code>azimuth,pitch,roll</code>
 +
|Measured in degrees. 0=North, 90=East, 180=South, 270=West; -180..180; -90..90
 +
|-
 +
|<code>pressure</code>
 +
|<code>p</code>
 +
|Atmospheric pressure in [http://en.wikipedia.org/wiki/Bar_(unit) millibars]
 +
|-
 +
|<code>proximity</code>
 +
|<code>p</code>
 +
|Proximity in centimeters
 +
|-
 +
|<code>rotation_vector</code>
 +
|<code></code>
 +
|
 +
|-
 +
|<code>temperature</code>
 +
|<code></code>
 +
|
 +
|-
 +
|}
 +
 +
--[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:28, 27 March 2012

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

Phonebot.service-lifecycle.png

Object reference

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 manipulated 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")

Sensor types:

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

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