Webinos Logo

The Generic Actuator API

Webinos API Specifications

4 Sep 2012

Authors


Abstract

The webinos Generic Actuator API provides applications with an API to control actuators.

Table of Contents

  1. Introduction
  2. Interfaces and Dictionaries
    1. ActuatorRange
    2. Actuator
    3. PendingOperation
    4. ActuatorEvent
  3. Callbacks
    1. ActuatorSuccessCB
    2. ActuatorErrorCB
  4. Features
  5. Full WebIDL

Summary of Methods

Interface Method
ActuatorRange
Actuator PendingOperation setValue(float[] value, ActuatorSuccessCB successCB, ActuatorErrorCB errorCB)
PendingOperation void cancel()
ActuatorEvent void initActuatorEvent(DOMString type, DOMString actuatorType, DOMString actuatorId, float[] actualValue)

Introduction

The webinos Generic Actuator API provides applications with an API to control actuators in the device, connected to the device or in another device.

The API is agnostic to underlying low level methods for actuator discovery and communication with actuators. However, the Actuator API should be used in combination with the general webinos service discovery methods findServices() and bind(). The actuator services can be located in the user's personal zone or be shared on the current network.

Currently several different actuator types are defined but the API could easily be extended with additional actuator types.

This is an experimental API and security and privacy issues are not specifically addressed in the specification. If access to security or privacy sensitive actuators are provided the user agent must either acquire access permission through a user interface or control access through a prearranged trust relationship with users.

Interfaces and Dictionaries

Interface ActuatorRange

This interface defines an abstract class representing the range of the actuator values. The actuator range can be an interval (e.g. temperature is in interval [0°C,27°C]) or a set of valid values (e.g. a switch accepts only the values {0,1} representing the ON and OFF state).

WebIDL
        interface ActuatorRange {
        };
Code example
        // Handle that can be used to cancel the ongoing asynchronous discovery process.
        var findHandle = 0;

        // Handle from service.bind.
        var actuatorHandle = 0;

        // Array of found switch actuators object.
        var availableSwitchActuators = {};
                 
        // Callback method that displays a list of found actuators in a selection list
        // The selection list is dynamically extended every time a new actuator is discovered.
        function actuatorFoundCB(actuator) {

                var selectlist = document.getElementById('actuatorlist');
                var option = document.createElement('option');
                option.value = actuator.id;
                option.appendChild(document.createTextNode(actuator.displayName));
                availableSwitchActuators [actuator.id] = actuator;
                selectlist.appendChild(option);

        }
                      
 
       // Callback when bind has been successfully executed on the service object. The Actuator is authorized and ready to use
        function bindCB(myActuator) {
                alert('Actuator ' + myActuator.displayName + ' with ID: ' + myActuator.id + ' selected');
                                var ON = 1.0;
                                var OFF = 0.0;
                                var successCB = function(evt){
                                        alert('Switch Actuator ' + myActuator.displayName + ' is now '+ (evt.actualValue[0] == ON? 'ON': 'OFF'));
                                        if(evt.actualValue[0] == ON){
                                                // turn OFF after 5 Seconds 
                                                setTimeout(function(){
                                                        myActuator.setValue([OFF],successCB,errorCB);
                                                },5000);
                                        }       
                                };
                                var errorCB = function(err){
                                        alert('Error on change the state of the Switch Actuator ' + myActuator.displayName);
                                };
                                // Turn Switch ON
                                myActuator.setValue([ON],successCB,errorCB);
        }


       // Callback method that is invoked when user selects an option in the actuator selection list 
        function actuatorSelected(actuator) {

                // Stops the findServices operation
                findHandle.cancel();

                // Binds to the actuator API to initiate an authorized objects used to
                // invoke services.  
                actuatorHandle = actuator.bind({onBind:bindCB});                               
                
        }
        
        // Get list of switch actuators registered in the device through the Service Discovery findServices() method
        findHandle  = window.webinos.discovery.findServices({api:'http://webinos.org/api/actuators.switch'}, {onFound:actuatorFoundCB});
 
       // Handle user selection of actuator
        var actuatorlist = document.getElementById('actuatorlist');
        actuatorlist.addEventListener("change", function (e) {
                                var actuator = availableSwitchActuators[e.target.value];
                                if (actuator) {
                                    actuatorSelected(actuator);
                                }
        }, false);


 

Interface Actuator

This interface defines the actuator properties. It is an actuator specific extension to the interface Service in the ServiceDiscovery module.

WebIDL
        [NoInterfaceObject] interface Actuator : Service {


                readonly attribute ActuatorRange[] range;
 

                readonly attribute DOMString[] unit;


                readonly attribute DOMString? vendor;  


                readonly attribute unsigned long?  version;


                PendingOperation setValue (float[] value, optional ActuatorSuccessCB successCB, optional ActuatorErrorCB errorCB);
        };

Attributes

readonly ActuatorRange[] range

The range of each actuator value.

The size of the range array must be the same as the number of input pins of the actuator

This attribute is readonly.
readonly DOMString[] unit

The unit of each actuator value.

The unit array and the range array must have the same size, which represents the number of input pins of the actuator

This attribute is readonly.
readonly DOMString? vendor

Vendor string of this actuator.

This attribute is readonly.
readonly unsigned long? version

Version of the actuators module.

This attribute is readonly.

Methods

setValue

Set a new actuator value.

Signature
PendingOperation setValue(float[] value, optional ActuatorSuccessCB successCB, optional ActuatorErrorCB errorCB);
Parameters
  • value
    • Optional: No.
    • Nullable: No
    • Type: array
    • Description: an array of new actuator values. The size of the value array is the same as the number of input pins of the actuator.
  • successCB
    • Optional: Yes.
    • Nullable: No
    • Type: ActuatorSuccessCB
    • Description: the success callback called with an ActuatorEvent object as input in case the setValue call succeeded.
  • errorCB
    • Optional: Yes.
    • Nullable: No
    • Type: ActuatorErrorCB
    • Description: the error callback

Interface PendingOperation

The PendingOperation interface

WebIDL
        [NoInterfaceObject] interface PendingOperation {


            void cancel ();
        };

The PendingOperation interface describes objects that are returned by asynchronous methods that are cancellable. It makes it possible to bring these operations to a stop if they haven't produced a result within a desired time or before a given event, thereby possibly reclaiming resources.

Methods

cancel

Method Cancel

Signature
void cancel();

Cancels the pending setValue() asynchronous operation. When this method is called, the user agent must immediately bring the operation to a stop and return. Allocated resources should be released and any ongoing related network operations should be terminated. An error callback is issued with the DOMError name "AbortError". If the set value operation is no longer under control of the calling process, the cancel function will be ignored and all neccessary 'housekeeping functions' required after starting the set value process will be performed as if the cancel had never been issued.

Interface ActuatorEvent

This interface defines the actuator data type.

WebIDL
        interface ActuatorEvent {

                readonly attribute DOMString actuatorType;


                readonly attribute DOMString? actuatorId;


                readonly attribute float[] actualValue;


                void initActuatorEvent(DOMString type, DOMString actuatorType, DOMString actuatorId, float[] actualValue); 
        };

Attributes

readonly DOMString actuatorType

The type of the actuator. This is a URI defining the actuator type according to the defined actuator "feature" URI strings.
For the defined actuator types the actualValue array contains the following data:

http://webinos.org/api/actuators.switch:
actualValue[0] = the actual state of the switch. OFF=0, ON=1

This attribute is readonly.
readonly DOMString? actuatorId

The unique identity of the of the specific actuator

This attribute is readonly.
readonly float[] actualValue

Array of actual values representing the current state of the actuator

This attribute is readonly.

Methods

initActuatorEvent

Method to set initial values of actuator event.

Signature
void initActuatorEvent(DOMString type, DOMString actuatorType, DOMString actuatorId, float[] actualValue);
Parameters
  • type
    • Optional: No.
    • Nullable: No
    • Type: DOMString
    • Description: Event type i.e. 'actuator'
  • actuatorType
    • Optional: No.
    • Nullable: No
    • Type: DOMString
    • Description: Actuator type as a feature URI
  • actuatorId
    • Optional: No.
    • Nullable: No
    • Type: DOMString
    • Description: The unique identity of the specific actuator
  • actualValue
    • Optional: No.
    • Nullable: No
    • Type: array
    • Description: Array of actual value

Callbacks

ActuatorSuccessCB

onSuccess The onSuccess method is called after the setValue succeeded.

WebIDL
                callback ActuatorSuccessCB =  void (ActuatorEvent event);
Signature
void ActuatorSuccessCB(ActuatorEvent event);
Parameters
  • event
    • Optional: No.
    • Nullable: No
    • Type: ActuatorEvent
    • Description: The event object associated to the asynchronous operation setValue

ActuatorErrorCB

The ActuatorErrorCB method is called if an error occurs during the setValue() process.

WebIDL
       callback ActuatorErrorCB = void (DOMError error);
Signature
void ActuatorErrorCB(DOMError error);
Parameters
  • error
    • Optional: No.
    • Nullable: No
    • Type: DOMError
    • Description: DOMError object detailing what went wrong in an unsuccessful setValue() asynchronous operation. The following error names could be issued:
      - "SyntaxError": Input parameters did not match the expected pattern or value is not in range.
      - "AbortError": Operation was aborted by the user.
      - "TimeoutError": The operation timed out.

Features

This is the list of URIs used to declare this API's features, for use in the widget config.xml and as identifier for service type in service discovery functionality. For each URI, the list of functions covered is provided.

http://webinos.org/api/actuators

Identifies all the actuator types.

http://webinos.org/api/actuators.switch

Identifies the switch actuator type. A switch actuator has only one input pin which represents the state of the switch. range = {0,1} (OFF = 0, ON = 1).

http://webinos.org/api/actuators.linearmotor

Identifies the linear motor actuator type. A linear motor actuator has only one input pin which represents the speed and the direction of the movement. Positive values for forward direction, negative values for backwards direction. the absolute value represents the speed of the movement in km/h.

http://webinos.org/api/actuators.rotationalmotor

Identifies the rotational motor actuator type. A rotational motor actuator has only one input pin which represents the speed and the direction of the rotation. Positive values for clockwise rotational direction, negative values for counter clockwise rotational direction. the absolute value represents the rotational speed in Hz (Herz = cycles per second).

http://webinos.org/api/actuators.vibratingmotor

Identifies the vibrating motor actuator type. A vibrating motor actuator has only one input pin which represents the normalized intensity of the vibration. only values in interval [0, 1] are valid. 0 means no vibration, 1 for maximal intensity.

http://webinos.org/api/actuators.servomotor

Identifies the servo motor actuator type. A servo motor actuator has only one input pin which represents the angular position of the output shaft in degree. The min und max values define the lower and upper bound for valid values of the angle

http://webinos.org/api/actuators.swivelmotor

Identifies the swivel motor actuator type. A swivel motor actuator has three input pins which represent the coordinate (x-y-z) of the swivel arm. The min und max values of each input pin define the lower and upper bound for valid values of each coordinate

http://webinos.org/api/actuators.thermostat

Identifies the thermostat actuator type. A thermostat has only one input pin which represents the desired temperature in °C. The min und max values define the lower and upper bound for valid temperature values

Full WebIDL

WebIDL
        interface ActuatorRange {
        };


        [Constructor(float minValue), Constructor(float minValue,float maxValue)]
        interface IntervalRange: ActuatorRange {

                attribute float minValue;

                attribute float maxValue;
        };


        [Constructor(float[] validValues)]
        interface ListRange: ActuatorRange {

                attribute float[] validValues;
        };

  

 
        [NoInterfaceObject] interface Actuator : Service {


                readonly attribute ActuatorRange[] range;
 

                readonly attribute DOMString[] unit;


                readonly attribute DOMString? vendor;  


                readonly attribute unsigned long?  version;


                PendingOperation setValue (float[] value, optional ActuatorSuccessCB successCB, optional ActuatorErrorCB errorCB);
        };


                callback ActuatorSuccessCB =  void (ActuatorEvent event); 



       callback ActuatorErrorCB = void (DOMError error);
                


        [NoInterfaceObject] interface PendingOperation {


            void cancel ();
        };




        interface ActuatorEvent {

                readonly attribute DOMString actuatorType;


                readonly attribute DOMString? actuatorId;


                readonly attribute float[] actualValue;


                void initActuatorEvent(DOMString type, DOMString actuatorType, DOMString actuatorId, float[] actualValue); 
        };