Dirimote Developer Documentation
- Getting started
- Purpose
- Hello Dirimote
- Sessions and Connections
- Controller Initialisation
- Interaction Data Handling
- Default Interfaces
- Custom Interfaces
- Error Handling
Getting started
- 1. Download the Dirimote library from https://github.com/at2software/dirimote or http://www.dirimote.com/downloads/sdk/dirimote_sdk-latest.zip
- 2. Import flash/lib/libDirimote.swc into your project
- 3. Get an App ID on http://www.dirimote.com/member
Purpose
The Dirimote flash/as3 library for developers, provides easy to use classes and methods to get Dirimote functionality into your own applications and projects. For a quick introduction see http://www.dirimote.com and http://www.dirimote.com/demo If you are not a developer and want to use or test Dirimote, then visit http://www.dirimote.com with your iPhone, iPad or Android device and download the Dirimote App for free.Hello Dirimote
Using Dirimote is as simple as this
Create a new Dirimote object:
dirimote= new Dirimote(APPID);
Create a Controller object:
controller= dirimote.createController(new DirimoteInterfaceLayout("default"));
Start listening to interaction data, sent by remote controllers:
controller.addEventListener(DirimoteController.EVENT_INTERACTION, onControllerInteraction);
Display the session QR-Code somewere visible at your stage:
stage.addChild(controller.qrcode);
Complete example:
package com.at2.dirimote.examples.HelloDirimote
{
import com.at2.dirimote.receiver.*;
import com.at2.dirimote.common.*;
import flash.display.Sprite;
import flash.events.Event;
public class Main extends Sprite
{
//register an App on http://www.dirimote.com/ and get an APPID for your application
private const APPID:String = "MY_APP_ID";
private var dirimote:Dirimote = null;
private var controller:DirimoteController= null;
public function Main():void
{
if (stage) init();
else addEventListener(Event.ADDED_TO_STAGE, init);
}
private function init(e:Event = null):void
{
removeEventListener(Event.ADDED_TO_STAGE, init);
dirimote = new Dirimote(APPID);
controller= dirimote.createController(new DirimoteInterfaceLayout("default"));
controller.addEventListener(DirimoteController.EVENT_INTERACTION, onControllerInteraction);
stage.addChild(controller.qrcode);
}
private function onControllerInteraction(e:Object):void {
if(e.id== DirimoteActions.DIRIMOTE_ACTION_A){
trace('Hello World!');
}
}
}
}
Sessions and Connections
There are two types of sessions - regular sessions and static sessions. Regular sessions are created automatically and remain, if not manually disabled, valid for at least 3 days. Static sessions dont expire. They are bound to your application and can be managed at http://www.dirimote.com/member. Static sessions allow to use fixed DIRI-Codes e.g. for print.On object creation, Dirimote starts a session and connects automatically. Unwanted disconnects are handled automatically as well. You can change this behavior by using the following methods.
Use a regular session and disable connect/reconnect:
var auto_connect:Boolean = false; //default true var auto_reconnect:Boolean = false; //default true dirimote = new Dirimote(APP_ID, auto_connect, auto_reconnect);
Manual connect/reconnect:
dirimote.connect(); //... dirimote.reconnect();
Enable/Disable auto reconnect:
dirimote.autoReconnect= false;
Calling this method will invalidate the current session, disconnect all controllers, disconnect your application and set auto reconnect to false. Note that static sessions don't get invalidated.
dirimote.closeSession();
You can disconnect remote controllers any time, by calling the disconnect method:
controller.disconnect();
Use a static session:
var static_session:String= "MY_STATIC_SESSION"; //default null for regular session dirimote= new Dirimote(APP_ID, auto_connect, auto_reconnect, static_session);
Controller Initialisation
To create a controller you need to create a default controller user interface first. It is shown at the user's display, when connecting to your application. To create a interface layout object you can either use a predefined interface layout or build your own custom interfaces.This creates a interface layout with two directional buttons (up/down) and two action buttons (A/B). id must be a unique identifier for your interface layout. See also Default Interfaces.
id = "default"; type = DirimoteInterfaceLayout.DIRIMOTE_UI_2DIR_H_2ACT_BUTTONS; layout = new DirimoteInterfaceLayout(id, type);
To use your own interface layout, set the type to DIRIMOTE_UI_CUSTOM_INTERFACE and add the path to your xml file. See also Custom Interfaces.
id = "default"; type = DirimoteInterfaceLayout.DIRIMOTE_UI_CUSTOM_INTERFACE; xml = "hello_interface.xml" layout = new DirimoteInterfaceLayout(id, type, xml);
This creates a new controller with layout used as default ui.
controller= dirimote.createController(layout);
You can create up to 15 independent controllers which can be connected simultaneously. All of them may but need not share the same interface layouts. You can access controllers by creation id using the getController(id:int) method.
controller_0= dirimote.createController(layout); controller_1= dirimote.createController(layout); controller_2= dirimote.createController(layout); dirimote.createController(layout2); controller_3= dirimote.getController(3);
You can add more interface layouts at any time and..
controller.addInterfaceLayout(layout3);
..freely switch between them, while a remote controller is connected to your application.
controller.changeInterfaceLayout(id);
You can obtain additional user information from controllers.
options = { username:true, avatar:true };
controller= dirimote.createController(layout, options);
...
private function onControllerReady(e:Event):void {
if(controller.avatar && controller.username){
stage.addChild(controller.avatar);
trace(controller.username);
}
}
Events
To get any data from remote controllers, you need to set event listeners to your controller objects. Available events are:Happens when a remote controller connects to your application and starts receiving settings like interfaces from your application. The remote controller won't listen to or send any commands or interaction data until it emits EVENT_READY.
DirimoteController.EVENT_CONNECTED
Indicates that the remote controller is connected to your application and ready to receive and send commands:
DirimoteController.EVENT_READY
Happens when the remote controller changed its interface layout e.g. because you called controller.changeInterfaceLayout earlier:
DirimoteController.EVENT_INTERFACE_CHANGED
The remote controller disconnected. The QR-code will get visible again automatically to let the next user connect to your application:
DirimoteController.EVENT_DISCONNECTED
This event is sent whenever the user interacts with the controller e.g. presses a button. See also Interaction Data Handeling.
DirimoteController.EVENT_INTERACTION
Interaction Data Handling
To get any interaction data, you need to add an event listener to a controller object and listen for interaction data events.
controller.addEventListener(DirimoteController.EVENT_INTERACTION, onControllerInteraction);
...
private function onControllerInteraction(e:Object):void {
if(e.id == DirimoteDefaultControls.DIRIMOTE_ACTION_A){
select(e.etype){
case DirimoteEventTypes.TOUCH:
trace('A button: TOUCH');
break;
case DirimoteEventTypes.TOUCH_DOWN:
trace('A button: TOUCH_DOWN');
break;
case DirimoteEventTypes.TOUCH_UP:
trace('A button: TOUCH_UP');
break;
default:
break;
}
}
if(e.id == DirimoteDefaultControls.DIRIMOTE_DIRECTION_DOWN){
...
}
if(e.id == 'my_button'){
...
}
if(e.id == DirimoteDefaultControls.DIRIMOTE_TOUCHAREA){
trace('touch point: x:'+e.data.x+' y:'+e.data.y);
select(e.etype){
...
case DirimoteEventTypes.TOUCH_MOVE:
trace('touch area: TOUCH_MOVE');
break;
...
}
}
if (e.id == DirimoteDefaultControls.DIRIMOTE_ACCELEROMETER) {
trace('accelerometer data: x: ' + e.data.x + ' y: ' + e.data.y + ' z: ' + e.data.z);
}
}
Depending on your interface layout the following events may occur. See Default Interfaces and Custom Interfaces for additional information.
DirimoteEventTypes.TOUCH_DOWN DirimoteEventTypes.TOUCH_UP DirimoteEventTypes.TOUCH_MOVE DirimoteEventTypes.TOUCH //TOUCH_DOWN followed by a TOUCH_UP DirimoteEventTypes.ACCELERATE
Default Interfaces
These are currently usable default interface layouts.| Type | DirimoteDefaultControls(IDs) | Example |
|---|---|---|
| DIRIMOTE_UI_2DIR_H_2ACT_BUTTONS |
|
 |
| DIRIMOTE_UI_2DIR_H_4ACT_BUTTONS |
|
 |
| DIRIMOTE_UI_2DIR_V_2ACT_BUTTONS |
|
 |
| DIRIMOTE_UI_2DIR_V_4ACT_BUTTONS |
|
 |
| DIRIMOTE_UI_4DIR_2ACT_BUTTONS |
|
 |
| DIRIMOTE_UI_4DIR_4ACT_BUTTONS |
|
 |
| DIRIMOTE_UI_8DIR_2ACT_BUTTONS |
|
 |
| DIRIMOTE_UI_8DIR_4ACT_BUTTONS |
|
 |
| DIRIMOTE_UI_TOUCH_FIELD | DIRIMOTE_TOUCHAREA |  |
| DIRIMOTE_UI_ACCEL_NO_BUTTONS | DIRIMOTE_ACCELEROMETER |
Custom Interfaces
Custom interfaces are defined using XML:
<?xml version="1.0" encoding="UTF-8"?>
<interface>
<settings>
<backgroundcolor>0x339933
</settings>
<ui>
<item>
<id>TestButton
<type>button
<bitmap>assets/button.png
<mode>verbose
<xPos>384
<yPos>104
</item>
<item>
<id>TestImage
<type>image
<bitmap>assets/logo.png
<xPos>1130
<yPos>570
</item>
</ui>
</interface>
UI objects are added to the interface layout, by adding item nodes to the ui node. They are added to the remote controller's stage in the order they are defined in the xml file. If they overlap, the most recently added item appears on top. UI items contain the following attributes:
id - unique identifier
type - type of the item (image | button | toucharea | accelerometer)
bitmap - relative path to an image file
xPos - center position x of the item (0-1280)
yPos - center position y of the item (0-720)
mode - affects the transmitted data (basic | eco | verbose)
Item Types
Currently there are 4 different item types:image, button, toucharea and accelerometer.toucharea and accelerometer can only be added once per interface. The special type exitbutton should only be used in exceptional cases.
Image
Displays an image and doesn't cause interaction data. Use this to add a background image or a logo for example.Button
Buttons are displayed like images but if the user presses or releases them, interaction data is sent from the remote controller to your application. To get the data, you need to add a EVENT_INTERACTION event listener to the corresponding controller object.<item> <id>myButton_ID <type>button <bitmap>my_button.png <mode>basic <xPos>640 <yPos>360 </item>
mode
basic - send TOUCH events only
eco and verbose - send TOUCH, TOUCH_DOWN and TOUCH_UP events
private function onControllerInteraction(e:Object):void {
if(e.id == "myButton_ID" && e.etype == DirimoteEventTypes.TOUCH){
//handle ''myButton_ID'' touched event
}
}
Touch
<item> <id>toucharea <type>toucharea <bitmap>toucharea.png <xPos>640 <yPos>360 <mode>basic </item>
mode
basic - don't send TOUCH_MOVE events
eco - send TOUCH_MOVE events once every 500ms
verbose - try to send all triggered TOUCH_MOVE events
Accelerometer
<item> <id>accelerometer <type>accelerometer <mode>basic </item>
mode
basic - 1000ms update interval
eco - 500ms update interval
verbose - 100ms update interval
Exit
If an item of type exitbutton is defined, it takes over the function of the Back button of the remote controller, while the custom interface is displayed. The default Back button will be hidden. The exit button acts similar to a regular button. However, no interaction data is sent on button press or release. If the button is pressed, the remote controller disconnects.<item> <id>exitbutton <type>exitbutton <bitmap>exit.png <xPos>20 <yPos>20 </item>
Error Handling
dirimote.addEventListener(Dirimote.EVENT_ERROR, onDirimoteError);
...
private function onDirimoteError(e:Event):void {
trace(dirimote.statusMsg);
}