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

From EtherWiki
Jump to: navigation, search
(→‎Sensor events)
 
(15 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
Services are non-visual components that monitor different environment states and trigger an event when the state changes. The available services are:
 
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
+
* email - Send email
−
* phone - Monitor phone events
+
* http - Make web requests and retrieve response
 +
* phone - Monitor phone events and send SMS messages
 
* sensor - Monitor hardware sensors
 
* sensor - Monitor hardware sensors
 
* timer - Alert at specific intervals
 
* timer - Alert at specific intervals
Line 9: Line 10:
  
 
# The service's <code>OnUpdate</code> event fires
 
# The service's <code>OnUpdate</code> event fires
−
# The application's <code>OnService</code> event fires
+
# The [[Phonebot_developer%27s_reference/Object_reference#Application|application]]'s <code>OnService</code> event fires
−
# The current module's <code>OnService</code> event fires
+
# The current [[Phonebot_developer%27s_reference/Object_reference#Module|module]]'s <code>OnService</code> event fires
  
−
Each Service stores its update data in a queue. The methods <code>get_event()</code> and <code>pop_event()</code> access the next event in the queue; <code>event_size</code> returns how many events exist; <code>clear_events</code> clears the queue.
+
Each Service stores its update data in a queue. The methods <code>get_event()</code> and <code>pop_event()</code> access the next event in the queue; <code>event_size</code> returns how many events exist; <code>clear_events()</code> clears the queue.
  
−
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 <code>OnUpdate</code> and <code>OnService</code> event will determine how responsive your application is when reading sensor data. If updates are sluggish, try reducing the buffer size.
+
The maximum number of sensor events that will be retained in the queue is controlled by the "Sensor buffer" [[Phonebot properties|Phonebot property]]. The "Sensor buffer" value, the sensor service's "Minimum update frequency" value, and the amount of script within each <code>OnUpdate</code> and <code>OnService</code> event will determine how responsive your application is when reading sensor data. If updates are sluggish, try reducing the buffer size.
 +
 
 +
A [[Phonebot_developer%27s_reference/Object_reference#Module|module]]'s show_file_dialog() method can be considered a module-level service.
  
 
== Service lifecycle ==
 
== Service lifecycle ==
Line 100: Line 103:
 
|-
 
|-
 
|}
 
|}
 +
 +
=== Service properties ===
  
 
In addition to the common properties, methods, and events, each service may have custom properties accessible from the get_property() and set_property() methods:
 
In addition to the common properties, methods, and events, each service may have custom properties accessible from the get_property() and set_property() methods:
Line 108: Line 113:
 
!Properties
 
!Properties
 
!Description
 
!Description
 +
|-
 +
|<code>email</code>
 +
|<code>attachments</code> - [[Phonebot_developer%27s_reference/Object_reference#Json|JSON]] array containing a JSON object with a name and a data or path field. Name contains the file name with an extension denoting the content type. Data contains the byte array of the file contents retrieved by calling any of the [[Phonebot_developer%27s_reference/Object_reference/Using_the_Phonebot_file_object|file.read()]] methods. Path contains the local path to the file. If path is present, data will be ignored. Either of the following is valid:
 +
 +
{"name":"%name%", "path":"%path%"}
 +
 +
{"name":"%name%", "data":"%data%"}
 +
 +
<code>body</code>
 +
 +
<code>cc</code> - email addresses separated by commas
 +
 +
<code>reply_to</code> - a single email address
 +
 +
<code>subject</code>
 +
 +
<code>to</code> - email addresses separated by commas
 +
|Send an email. Returns a single event in the queue containing the following values:
 +
 +
http_response,error_code,error_description
 +
 +
If http_response is 200, error_code will be 0 and error_description will be "OK". Any other response will provide error values.
 +
 +
The following restrictions are put on sending emails:
 +
 +
{|class="wikitable"
 +
|-
 +
!Restriction
 +
!Phonebot
 +
!Phonebot Plus
 +
|-
 +
|Number of emails in past 24 hour
 +
|5
 +
|100
 +
|-
 +
|Number of recipients per email
 +
|1
 +
|20
 +
|}
 +
 +
Emails will be received from the address <code>"Phonebot Email Service" pbot.email@gophonebot.com</code>. Email is sent using the Postmark Web service. Refer to their [http://postmarkapp.com/privacy-policy privacy policy] for information on how information is used.
 +
 
|-
 
|-
 
|<code>http</code>
 
|<code>http</code>
−
|<code>url</code>
+
|<code>data</code> - the data sent for a POST
−
|Makes a GET request to a URL. Returns a single event in the queue containing the response.
+
 
 +
<code>headers</code> - a [[Phonebot_developer%27s_reference/Object_reference#Map|map]] of header names to values
 +
 
 +
<code>method</code> - the request method: GET or POST
 +
 
 +
<code>url</code> - the URL
 +
|Makes a request to a URL. Returns a single event in the queue containing the response.
 
|-
 
|-
 
|<code>phone</code>
 
|<code>phone</code>
 
|<code>events</code> - array of event names
 
|<code>events</code> - array of event names
 +
 +
<code>sms_to</code> - SMS address
 +
 +
<code>sms_text</code> - the SMS content
 
|Monitors one or more phone events. Returns an event containing a comma-delimited list of values beginning with the event name (e.g. <code>data_activity,4</code>). The range of each value is dependent on the event.
 
|Monitors one or more phone events. Returns an event containing a comma-delimited list of values beginning with the event name (e.g. <code>data_activity,4</code>). The range of each value is dependent on the event.
 +
 +
If <code>sms_to</code> is set, the contents of <code>sms_text</code> will be sent via SMS. Returns two events in the queue containing the following values:
 +
 +
sms_sent,error_code,error_description
 +
sms_received,error_code,error_description
 +
 +
If error_code is 0, error_description will be "OK". Any other response will provide error values.
 
|-
 
|-
 
|<code>sensor</code>
 
|<code>sensor</code>
Line 162: Line 226:
 
!Description
 
!Description
 
|-
 
|-
−
|<code></code>
+
|<code>call_forwarding</code>
−
|<code></code>
+
|<code>cfi</code>
 +
|boolean
 +
|-
 +
|<code>call_state</code>
 +
|<code>state,incoming_number</code>
 +
|state: 0 - idle, 1 - ringing, 2 - off hook
 +
|-
 +
|<code>cell_location</code>
 +
|<code>"cdma",base_station_id,base_station_latitude,base_station_longitude,system_id,network_id</code>
 +
<code>"gsm",lac,cid</code>
 +
|
 +
|-
 +
|<code>data_activity</code>
 +
|<code>direction</code>
 +
|0 - none, 1 - in, 2 - out, 3 - in/out, 4 - dormant
 +
|-
 +
|<code>data_connection_state</code>
 +
|<code>state,network_type</code>
 +
|state: 0 - disconnected, 1 - connecting, 2 - connected, 3 - suspended
 +
|-
 +
|<code>message_waiting</code>
 +
|<code>mwi</code>
 +
|boolean
 +
|-
 +
|<code>service_state</code>
 +
|<code>is_manual_selection,operator_alpha_long,operator_alpha_short,operator_numeric,roaming,state</code>
 +
|state: 0 - in service, 1 - out of service, 2 - emergency only, 3 - power off
 +
|-
 +
|<code>signal_strengths</code>
 +
|<code>cdma_ecio,evdo_dbm,evdo_ecio,evdo_snr,gsm_bit_error_rate,gsm_signal_strength,is_gsm</code>
 
|
 
|
 +
|-
 +
|<code>sms_delivered</code>
 +
|<code>error_code,error_description</code>
 +
|Generated when a sent SMS messages is delivered
 +
|-
 +
|<code>sms_received</code>
 +
|<code>timestamp,originating_address,message_body</code>
 +
|Generated when an SMS messages is received
 +
|-
 +
|<code>sms_sent</code>
 +
|<code>error_code,error_description</code>
 +
|Generated when an SMS messages is sent
 
|}
 
|}
 +
 +
--[http://developer.android.com/reference/android/telephony/PhoneStateListener.html PhoneStateListener]
  
 
=== Sensor events ===
 
=== Sensor events ===

Latest revision as of 16:38, 10 November 2012

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

  • email - Send email
  • http - Make web requests and retrieve response
  • phone - Monitor phone events and send SMS messages
  • sensor - Monitor hardware sensors
  • timer - Alert at specific intervals

When a service is updated, events are fired in the following order:

  1. The service's OnUpdate event fires
  2. The application's OnService event fires
  3. 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; event_size returns how many events exist; clear_events() clears the queue.

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.

A module's show_file_dialog() method can be considered a module-level service.

Service lifecycle

A service's properties, methods, and the application state affect that service's lifetime as the following diagram illustrates:

Phonebot.service-lifecycle.png

A service will start running:

  • When its start() method is called
  • If its autostart property is set to true, immediately after the application starts

A service will stop running:

  • When its stop() method is called
  • If its system property is set to false, when the application loses focus
  • If its system property is set to true, when the application exits

Object reference

Properties

Syntax Description
auto_start Read-only boolean. Set to true to start the service as soon as the application starts.
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.
system Read-only boolean. Set to true to have the service run even when the application has lost focus.
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 the value of a custom property (see below).
event = pop_event() Retrieve and delete the next event in the queue.
set_property(name, value) Set the value of a custom property (see below).
start() Start the service.
stop() Stop the service.

Events

Syntax Description
on_service

Service properties

In addition to the common properties, methods, and events, each service may have custom properties accessible from the get_property() and set_property() methods:

Service Properties Description
email attachments - JSON array containing a JSON object with a name and a data or path field. Name contains the file name with an extension denoting the content type. Data contains the byte array of the file contents retrieved by calling any of the file.read() methods. Path contains the local path to the file. If path is present, data will be ignored. Either of the following is valid: 
{"name":"%name%", "path":"%path%"}

{"name":"%name%", "data":"%data%"}

body

cc - email addresses separated by commas

reply_to - a single email address

subject

to - email addresses separated by commas

Send an email. Returns a single event in the queue containing the following values: 
http_response,error_code,error_description

If http_response is 200, error_code will be 0 and error_description will be "OK". Any other response will provide error values.

The following restrictions are put on sending emails:

Restriction Phonebot Phonebot Plus
Number of emails in past 24 hour 5 100
Number of recipients per email 1 20

Emails will be received from the address "Phonebot Email Service" pbot.email@gophonebot.com. Email is sent using the Postmark Web service. Refer to their privacy policy for information on how information is used.

http data - the data sent for a POST

headers - a map of header names to values

method - the request method: GET or POST

url - the URL

Makes a request to a URL. Returns a single event in the queue containing the response.
phone events - array of event names

sms_to - SMS address

sms_text - the SMS content

Monitors one or more phone events. Returns an event containing a comma-delimited list of values beginning with the event name (e.g. data_activity,4). The range of each value is dependent on the event.

If sms_to is set, the contents of sms_text will be sent via SMS. Returns two events in the queue containing the following values: 

sms_sent,error_code,error_description
sms_received,error_code,error_description

If error_code is 0, error_description will be "OK". Any other response will provide error values.

sensor minimum_update - time between updates in milliseconds

sensors - array of sensor names

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

Phone events

The phone service can be configured to return any combination of phone events. 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
call_forwarding cfi boolean
call_state state,incoming_number state: 0 - idle, 1 - ringing, 2 - off hook
cell_location "cdma",base_station_id,base_station_latitude,base_station_longitude,system_id,network_id

"gsm",lac,cid

data_activity direction 0 - none, 1 - in, 2 - out, 3 - in/out, 4 - dormant
data_connection_state state,network_type state: 0 - disconnected, 1 - connecting, 2 - connected, 3 - suspended
message_waiting mwi boolean
service_state is_manual_selection,operator_alpha_long,operator_alpha_short,operator_numeric,roaming,state state: 0 - in service, 1 - out of service, 2 - emergency only, 3 - power off
signal_strengths cdma_ecio,evdo_dbm,evdo_ecio,evdo_snr,gsm_bit_error_rate,gsm_signal_strength,is_gsm
sms_delivered error_code,error_description Generated when a sent SMS messages is delivered
sms_received timestamp,originating_address,message_body Generated when an SMS messages is received
sms_sent error_code,error_description Generated when an SMS messages is sent

--PhoneStateListener

Sensor events

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

Retrieved from "http://ether.scottdstrader.com/index.php?title=Phonebot_developer%27s_reference/Object_reference/Using_Phonebot_services&oldid=2078"