AIR Gamepad Protocol Overview

AIR Gamepad is a functionality available in Adobe AIR app, which enables Android smartphones and tablet devices to be used as wireless game controllers and second screen devices for desktop / browser games. AIR Gamepad allows a desktop game to connect to an Android device running the Adobe AIR app, and to load a custom game controller on its touch screen. The desktop game can listen to the user's touch and gesture events and to hardware events like accelerometer, magnetometer or gyroscope update events. The desktop game can also provide vibration feedback to the mobile device, which is useful when the user's visual attention would primarily be on the desktop screen.

AIR Gamepad Connection

AIR Gamepad functions as an independent Activity in Adobe AIR app. The AIR Gamepad Activity will be started or brought to foreground whenever a shake event is detected while the Adobe AIR app is running in the foreground. Whenever the AIR Gamepad Activity is brought to the foreground, a WebSocket server will be started in the mobile device to which a desktop application could connect and communicate.

When the AIR Gamepad Activity goes to the background, the WebSocket server and the active WebSocket connection to the server (if any) will be terminated. For example, if a phone call begins, or if the user presses the back button, the active connections to the WebSocket server will be terminated and the server will be stopped.

In this section, we discuss how a connection can be established between a desktop game and the WebSocket server running in AIR Gamepad.

Connecting the AIR Gamepad with a desktop application

At a given time, only one active connection with the WebSocket server is allowed. In case a new connection is attempted while another connection is already active, the WebSocket server will close the new connection with closing code 1003 (CLOSE_UNSUPPORTED). The active connection will remain unaffected.

To connect to AIR Gamepad's WebSocket server, the WebSocket client application must be in the same subnet as the Adobe AIR app. For example, the desktop running the Flash / HTML5 game that connects to AIR Gamepad, and the mobile device running the AIR app, must be connected to the same Wi-Fi network. In order to determine the IP address of the WebSocket server, the client application would need to request the user to provide the PIN displayed by AIR Gamepad Activity. The PIN is a 32 bit IPv4 address encoded as an unsigned integer with radix 32. The higher order bits of this 32 bit number represent the higher order components of the IP address (the network part), and the lower order bits represent the lower order components (the host part). The WebSocket server will be listening on the IPv4 address encoded as the PIN, using port number 1234. The URL for connecting to the WebSocket server can be constructed using this IP address and port number. The following is an example in ActionScript and JavaScript, to decode a PIN to the corresponding WebSocket URL.

function getGamepadURLFromPIN( pin:String ) :String {
var ipUint:Number = parseInt(pin.toUpperCase(), 32);
var port:Number = 1234;
var byteMask:Number = 0xFF;
var ip:String = ( ( ipUint >>> 24 ) & byteMask ).toString() + "." +
( ( ipUint >>> 16 ) & byteMask ).toString() + "." +
( ( ipUint >>> 8 ) & byteMask ).toString() + "." +
( ipUint & byteMask ).toString();
return "ws://"+ ip + ":" + port;
}
function getGamepadURLFromPIN( pin ) {
var ipUint = parseInt(pin.toUpperCase(), 32);
var port = 1234;
var byteMask = 0xFF;
var ip = ( ( ipUint >>> 24 ) & byteMask ).toString() + "." +
( ( ipUint >>> 16 ) & byteMask ).toString() + "." +
( ( ipUint >>> 8 ) & byteMask ).toString() + "." +
( ipUint & byteMask ).toString();
return "ws://"+ ip + ":" + port;
}

Using the constructed WebSocket URL, a desktop application would be able to open the WebSocket connection with AIR Gamepad. In order to complete the AIR Gamepad connection, the application must successfully perform the AIR Gamepad Handshake protocol immediately after opening the WebSocket connection. AIR Gamepad Handshake protocol is detailed in the next sub-section.

AIR Gamepad Handshake Protocol

The first message that reaches AIR Gamepad after opening a WebSocket connection must be the handshake message encoded as a UTF-8 string.


The handshake message must be a stringified JSON object with the following structure:

{
"protocol" : "WEBSOCKET",
"version" : "1.1.0",
"sourceID" : <A unique ID representing the message sender>,
"destinationID" : <The ID of the message receiver. This is the PIN displayed by the AIR Gamepad Activity>,
"publisher" : <Publisher name>,
"applicationURL" : <URL referring to the application>
}

The handshake message must reach the AIR app in a span of 30 seconds immediately after opening the WebSocket connection. If the handshake string does not reach the AIR app during this period, the AIR app will close the connection.


If the first message that reaches the AIR app after opening the WebSocket connection cannot be parsed from a string to the above JSON object structure, or if the handshake message is invalid (invalid protocol, unsupported version, invalid destination ID or invalid applicationURL), the WebSocket connection will be immediately closed with the error message sent in WebSocket close event's reason attribute.


As a response to a valid handshake message, the AIR app will send the following handshake response message as a stringified JSON object:

{
"protocol" : "WEBSOCKET",
"version" : <Requested API Version String>,
"sourceID" : <ID of the message sender>,
"destinationID" : <ID of the message receiver>
"publisher" : <Publisher name>,
"applicationURL" : <URL referring to the application>,
"status" : "SUCCESS"
}

The reception of the handshake response message at the desktop application indicates the successful completion of the AIR Gamepad connection. After the successful handshake, the WebSocket client application can start sending & receiving messages in order to perform various tasks using AIR Gamepad. The next section describes the structure of these messages and the various possible messages that can be sent across the AIR Gamepad connection.

AIR Gamepad Messages

After establishing a successful AIR Gamepad connection, the desktop application and AIR Gamepad would be able to communicate with each other using AIR Gamepad messages. AIR Gamepad messages are JSON objects that can be sent through the WebSocket connection after serializing them into UTF-8 encoded strings.

AIR Gamepad messages carry the information about the tasks that are need to be executed by AIR Gamepad and the events that happen in AIR Gamepad. Every AIR Gamepad message must carry the information about the intent or the task requested by the message, the millisecond time at which the message was generated and about the type of the message. An AIR Gamepad message can be of one of 3 types:

AIR Gamepad request

An AIR Gamepad request represents a message that can be sent by the desktop application, for which a corresponding response is expected from AIR Gamepad. Every AIR Gamepad request must hold a unique task ID using which the corresponding response will be mapped with. The AIR Gamepad request may be sent to perform a task in AIR Gamepad, for which the response will carry the information obtained after executing the task. The parameters for executing the task must be provided in the AIR Gamepad request as an array of items.

AIR Gamepad response

An AIR Gamepad response represents a message that is sent as a response to the corresponding AIR Gamepad request. For a desktop application to associate the corresponding requests and responses, every AIR Gamepad response will contain the unique task ID that was sent in the corresponding AIR Gamepad request. An AIR Gamepad response will also contain the information obtained after executing the requested task. This information will indicate if the task was successfully completed or not. If the task was completed successfully, the AIR Gamepad response will carry the information obtained after executing the task. Else, the AIR Gamepad response will carry an error message.

AIR Gamepad notification

An AIR Gamepad notification represents a message for which the sender does not expect a response. The AIR Gamepad notification may carry any associated information in a property. An AIR Gamepad notification may be used by the desktop application to execute a task in AIR Gamepad, for which a response message is not expected. Also, AIR Gamepad notifications are also used to send various events (touch, gesture, accelerometer, magnetometer, gyroscope and error events) from AIR Gamepad to the desktop application.

The structure of an AIR Gamepad message is described in the following section.

AIR Gamepad message format

An AIR Gamepad message must be a JSON object having properties with names header and data.

header property

The header property must be an object that holds properties with the following names:
title: A string value indicating the intent of the message. The section on AIR Gamepad Tasks will specify the various possible values that a title could take.

  • timestamp: A number value holding the millisecond epoch time when the message was created.
  • type: A string value indicating the type of the message. Only 3 values are allowed: REQUEST, RESPONSE and NOTIFICATION that indicates if the given message is an AIR Gamepad request, AIR Gamepad response or AIR Gamepad notification respectively.
  • taskID: A unique string value present on each AIR Gamepad request or AIR Gamepad response. It is used to map an AIR Gamepad response with the corresponding AIR Gamepad request.
  • status: A string value present on an AIR Gamepad response, identifying if the task requested by an AIR Gamepad request was completed successfully or not. The only 2 status values allowed are, SUCCESS and ERROR.

data property

The data property must be an object that holds properties with the following names:

  • arguments: An array value present on an AIR Gamepad request, holding the list of parameters that must be provided as the part of a request.
  • result: An object present on an AIR Gamepad response, holding the result for its corresponding request. Based on the status of response message, it will contain the following properties:
    • message: If the AIR Gamepad response's status value is ERROR, this property will hold the error message string.
    • *: If the AIR Gamepad response's status value is SUCCESS, the result object can have any relevant property(s) in it.
  • notification: An object present on an AIR Gamepad notification, holding any relevant property(s) in it.

Based on the above description, we can represent a given AIR Gamepad Request, AIR Gamepad Response and AIR Gamepad Notification as specified in the following sub-sections.

AIR Gamepad request

The following JSON object represents an AIR Gamepad request:

{
"header" : {
"title" : <A string value identifying the type of task that needs to be executed>,
"timestamp" : <A number value holding the millisecond epoch time when the request is created>,
"type" : "REQUEST",
"taskID" : <A unique string value that must be used to map the corresponding AIR Gamepad response>
},
"data" : {
"arguments" : [ <An array of parameters that are needed for execution of the task> ]
}
}

AIR Gamepad response

An AIR Gamepad response will be a JSON object sent as a response to the corresponding AIR Gamepad request. An AIR Gamepad response can come with either SUCCESS or ERROR status value.


The following JSON object represents an AIR Gamepad response with SUCCESS status:

{
"header" : {
"title" : <A string value identifying the type of task that was executed. This value will be same as title property provided in the corresponding AIR Gamepad request>,
"timestamp" : <A number value holding the millisecond epoch time when the response was created>,
"type" : "RESPONSE",
"taskID" : <The taskID that was provided in the corresponding AIR Gamepad request>,
"status" : "SUCCESS"
},
"data" : {
"result" : { <An object containing any number of properties of any type, which holds the result of the corresponding request> }
}
}

The following JSON object represents an AIR Gamepad response with ERROR status:

{
"header" : {
"title" : <A string value identifying the type of task that was executed. This value will be same as title property provided in the corresponding AIR Gamepad request>,
"timestamp" : <A number value holding the millisecond epoch time when the response was created>,
"type" : "RESPONSE",
"taskID" : <The taskID that was provided in the corresponding AIR Gamepad request>,
"status" : "ERROR"
},
"data" : {
"result" : {
"message" : < A string value holding the error message >
}
}

AIR Gamepad notification

The following JSON object represents an AIR Gamepad request:

{
"header" : {
"title" : <A string value identifying the intent of the notification. eg. an identifier for the type of task that needs to be executed or the type of event that is being sent from AIR Gamepad>,
"timestamp" : <A number value holding the millisecond epoch time when the notification is created>,
"type" : "NOTIFICATION"
},
"data" : {
"notification" : { <An object containing the information associated with the notification. eg. attributes of a touch event sent from AIR Gamepad, or the parameters specified by a desktop application to execute a task in AIR Gamepad> }
}
}

AIR Gamepad Tasks

An AIR Gamepad task represents a task that can be executed by AIR Gamepad on sending the corresponding AIR Gamepad request or AIR Gamepad notification. The title property in the AIR Gamepad request or AIR Gamepad notification would be used to identify the task that needs to be executed in AIR Gamepad.


The following subsections detail the various AIR Gamepad tasks that can be executed on AIR Gamepad, and the corresponding AIR Gamepad messages that are exchanged during the process.

Hardware Specifications Task

A hardware specifications task can be executed to fetch some details about the Android device's hardware. They include information about the dimensions of the device screen and whether or not a vibrator and motion sensors including accelerometer, magnetometer and gyroscope are available in the device.


A hardware specifications task can be executed using the following AIR Gamepad Request:

{
"header" : {
"title" : "HARDWARE_SPECIFICATIONS",
"timestamp" : <A number value holding the millisecond epoch time when the request is created>,
"type" : "REQUEST",
"taskID" : <A unique string value that must be used to map the corresponding AIR Gamepad response for this task>
},
"data" : {
"arguments" : []
}
}

As a response, AIR Gamepad would send the following AIR Gamepad Response:

{
"header" : {
"title" : "HARDWARE_SPECIFICATIONS",
"timestamp" : <A number value holding the millisecond epoch time when the response was created>,
"type" : "RESPONSE",
"taskID" : <The taskID that was provided in the corresponding AIR Gamepad request for this hardware specifications task>,
"status" : "SUCCESS"
},
"data" : {
"result" : {
"vibrator" : <A boolean value indicating if the vibrator is available on the device>,
"screenDimensions" : {
"height" : <A number value indicating the height of the device's display area in landscape orientation, in pixel units>,
"width" : <A number value indicating the width of the device's display area in landscape orientation, in pixel units>
},
"accelerometer" : <A boolean value indicating if the accelerometer is available on the device>,
"magnetometer" : <A boolean value indicating if the magnetometer is available on the device>,
"gyroscope" : <A boolean value indicating if the gyroscope is available on the device>,
}
}
}

Draw image task

A draw image task can be executed to draw a JPEG image on the device's screen. The image will be proportionally scaled to fit the width, and aligned to the bottom of the mobile screen. The JPEG image's binary data must be provided as a base-64 encoded string. A draw image task can be executed using the following AIR Gamepad Request:

{
"header" : {
"title" : "DRAW_IMAGE",
"timestamp" : <A number value holding the millisecond epoch time when the request is created>,
"type" : "REQUEST",
"taskID" : <A unique string value that must be used to map the corresponding AIR Gamepad response for this task>
},
"data" : {
"arguments" : [
<A string value containing a valid base-64 encoded JPEG image binary that will be drawn on the device's screen>
]
}
}

If the provided JPEG image was successfully decoded and rendered on the mobile screen, AIR Gamepad would send the following AIR Gamepad Response:

{
"header" : {
"title" : "DRAW_IMAGE",
"timestamp" : <A number value holding the millisecond epoch time when the response was created>,
"type" : "RESPONSE",
"taskID" : <The taskID that was provided in the corresponding AIR Gamepad request for this draw image task>,
"status" : "SUCCESS"
},
"data" : {
"result" : {}
}
}

Instead, if there occured an error while decoding and rendering the JPEG image on the screen, the requested image will not be rendered and AIR Gamepad would send the following AIR Gamepad Response:

{
"header" : {
"title" : "DRAW_IMAGE",
"timestamp" : <A number value holding the millisecond epoch time when the response was created>,
"type" : "RESPONSE",
"taskID" : <The taskID that was provided in the corresponding AIR Gamepad request for this draw image task>,
"status" : "ERROR"
},
"data" : {
"result" : {
"message" : <A string value holding the reason for the error occurred during this draw image task>
}
}
}

Vibrate task

A vibrate task can be executed to vibrate the device for a specified millisecond duration. If vibration is not supported by the device, an AIR Gamepad error log will be sent by the device.


A vibrate task can be executed using the following AIR Gamepad Notification:

{
"header" : {
"title" : "VIBRATE",
"timestamp" : <A number value holding the millisecond epoch time when the notification is created>,
"type" : "NOTIFICATION"
},
"data" : {
"notification" : {
"duration" : <A number value holding the millisecond duration for which the device should vibrate>
}
}
}

Touch event task

A touch event task can be executed to start or stop generating touch events when the user interacts with the device's touch screen. When the touch event generation has been started, every touch event detected at the device's touch screen will be sent to the desktop application as AIR Gamepad notifications.


A touch event task can be executed using the following AIR Gamepad Notification:

{
"header" : {
"title" : "TOUCH_EVENT",
"timestamp" : <A number value holding the millisecond epoch time when the notification is created>,
"type" : "NOTIFICATION"
},
"data" : {
"notification" : {
"start" : <A boolean value indicating if the device should start generating the touch events when the user is interacting with the touch screen. Set it as true to start generating the events and false to stop generating the events>
}
}
}

Once the touch event generation has been started, AIR Gamepad will be sending the various kinds of user touch events to the desktop application through AIR Gamepad Notifications. The type property in the notification identifies the type of the event that occured. The location of the event would be provided as localX and localY properties, which hold the pixel unit location on the screen in landscape orientation, with X axis from left to right and Y axis from top to bottom.

When the user starts a touch interaction, an event with type TOUCH_BEGIN will be generated. While the point of contact moves across the screen, events with type TOUCH_MOVE will be generated, along the location the interaction was detected. The touch event with type TOUCH_END will be generated at the location where the user stopped the touch interaction.


The touch events will be sent by AIR Gamepad to the desktop application as AIR Gamepad Notifications with the following structure:

{
"header" : {
"title" : "TOUCH_EVENT",
"timestamp" : <A number value holding the millisecond epoch time when the notification was created>,
"type" : "NOTIFICATION"
},
"data" : {
"notification" : {
"type" : <The type of the touch event. Possible values are: "TOUCH_BEGIN", "TOUCH_END" and "TOUCH_MOVE">,
"timestamp" : <A number value holding the millisecond epoch time when the touch event occured>,
"localX" : <The X axis location where the touch event occurred>,
"localY" : <The Y axis location where the touch event occurred>,
"isPrimaryTouchPoint" : <Indicates whether it is the first point of contact>,
"pressure" : <A value between 0.0 and 1.0 indicating force of the contact with the device. If the device does not support detecting the pressure, the value is 1.0>,
"sizeX" : <Width of the contact area in pixel units>,
"sizeY" : <Height of the contact area in pixel units>,
"touchPointID" : <A unique identification number (as an integer) assigned to the touch point>
}
}
}

Gesture event task

A gesture event task can be executed to start or stop generating various touch gesture events as the user interacts with the device's touch screen. Once the gesture event generation has been started, every gesture event detected at the device's touch screen will be sent to the desktop application as AIR Gamepad notifications.


A gesture event task can be executed using the following AIR Gamepad Notification:

{
"header" : {
"title" : "GESTURE_EVENT",
"timestamp" : <A number value holding the millisecond epoch time when the notification is created>,
"type" : "NOTIFICATION"
},
"data" : {
"notification" : {
"start" : <A boolean value indicating if the device should start generating the gesture events when the user is interacting with the touch screen. Set it as true to start generating the events and false to stop generating the events>
}
}
}

Once the gesture event generation has been started, AIR Gamepad will be sending the various kinds of touch gesture events to the desktop application through AIR Gamepad Notifications. The type property in the notification identifies the type of the event that occurred. The location of the event (if relevant) would be provided as localX and localY properties, which hold the pixel unit location on the screen in landscape orientation, with X axis from left to right and Y axis from top to bottom.

When the user starts a gesture interaction, an event with the corresponding type will be generated. The following is the list of gesture event types that are available in AIR Gamepad:

  • GESTURE_ZOOM: Indicates that the user performed a pinch to zoom gesture on the touch screen. The immediate change of scale in X and Y direction will be available in scaleX and scaleY properties, and the location of the event along the X and Y axis can be obtained from localX and localY properties.
  • GESTURE_ROTATE: Indicates that the user performed a rotate gesture on the touch screen. The immediate rotation angle will be available in the rotation property, and the location of the event along the X and Y axis can be obtained from localX and localY properties.
  • GESTURE_SWIPE: Indicates that the user performed a swipe gesture on the touch screen. The direction of swipe along X and Y axis can be detected using offsetX and offsetY properties, and the location of the event along the X and Y axis can be obtained from localX and localY properties.
  • GESTURE_PAN: Indicates that the user performed a two finger pan gesture on the touch screen. The location of the event along the X and Y axis can be obtained from localX and localY properties. The phase property indicates the phase of the event, which could be BEGIN, UPDATE or END.
  • GESTURE_TWO_FINGER_TAP: Indicates that the user performed a two finger tap on the touch screen. The location of the event along the X and Y axis can be obtained from localX and localY properties.

The gesture events will be sent by AIR Gamepad to the desktop application as AIR Gamepad Notifications with the following structure:

{
"header" : {
"title" : "GESTURE_EVENT",
"timestamp" : <A number value holding the millisecond epoch time when the notification was created>,
"type" : "NOTIFICATION"
},
"data" : {
"notification" : {
"type" : <The type of the gesture event, as listed above>,
"timestamp" : <A number value holding the millisecond epoch time when the gesture event occured>,
"localX" : <The X axis location where the gesture event occurred>,
"localY" : <The Y axis location where the gesture event occurred>,
"scaleX": <The horizontal scale of the gesture since the previous gesture event. For pan and swipe gesture events, its value is 1>,
"scaleY": <The vertical scale of the gesture since the previous gesture event. For pan and swipe gesture events, its value is 1>,
"rotation": <The current rotation angle, in degrees, of the gesture along the z-axis, since the previous gesture event. For pan and swipe gesture events, its value is 0>,
"offsetX": <The horizontal translation of the gesture from its position at the previous gesture event. For swipe event, it indicates horizontal direction: 1 for right and -1 for left>,
"offsetY": <The vertical translation of the gesture from its position at the previous gesture event. For swipe event, it indicates vertical direction: 1 for down and -1 for up>,
"phase": <The current phase in the event flow. For >,
"isTransform":false
}
}
}

Accelerometer event task

An accelerometer event task can be executed to start or stop generating accelerometer events from the device, within the specified interval. Once the accelerometer event generation has been started, the acceleration detected by the device will be sent to the desktop application as AIR Gamepad notifications.


An accelerometer event task can be executed using the following AIR Gamepad notification:

{
"header" : {
"title" : "ACCELEROMETER_EVENT",
"timestamp" : <A number value holding the millisecond epoch time when the notification is created>,
"type" : "NOTIFICATION"
},
"data" : {
"notification" : {
"start" : <A boolean value indicating if the device should start generating the accelerometer events. Set it as true to start generating the events and false to stop generating the events>,
"interval" : <A number value indicating the millisecond interval in which the accelerometer events must be sent. The events may be received faster or slower than the specified interval>
}
}
}

Once the accelerometer event generation has been started, AIR Gamepad will be sending the accelerometer events to the desktop application through AIR Gamepad Notifications. The "acc" property in the notification is an array containing the X, Y, Z coordinate values of the acceleration in m/s^2, along with the millisecond epoch time when the event was generated. The coordinate space of the accelerometer events has the origin at the center of the landscape oriented screen, with the X axis pointing from left to right, Y axis from bottom to top, and the Z axis pointing out of the screen, towards the user.


The accelerometer events will be sent by AIR Gamepad to the desktop application as AIR Gamepad Notifications with the following structure:

{
"header" : {
"title" : "ACCELEROMETER_EVENT",
"timestamp" : <A number value holding the millisecond epoch time when the notification was created>,
"type" : "NOTIFICATION"
},
"data" : {
"notification" : {
"acc" : [
<A number value holding the X coordinate value of the acceleration in m/s^2>,
<A number value holding the Y coordinate value of the acceleration in m/s^2>,
<A number value holding the Z coordinate value of the acceleration in m/s^2>,
<A number value holding the millisecond epoch time when the event was generated>
]
}
}
}

Magnetometer event task

A magnetometer event task can be executed to start or stop generating magnetometer events from the device, within the specified interval. Once the magnetometer event generation has been started, the magnetic field detected by the device will be sent to the desktop application as AIR Gamepad notifications.


A magnetometer event task can be executed using the following AIR Gamepad Notification:

{
"header" : {
"title" : "MAGNETOMETER_EVENT",
"timestamp" : <A number value holding the millisecond epoch time when the notification is created>,
"type" : "NOTIFICATION"
},
"data" : {
"notification" : {
"start" : <A boolean value indicating if the device should start generating the magnetometer events. Set it as true to start generating the events and false to stop generating the events>,
"interval" : <A number value indicating the millisecond interval in which the magnetometer events must be sent. The events may be received faster or slower than the specified interval>
}
}
}

Once the magnetometer event generation has been started, AIR Gamepad will be sending the magnetometer events to the desktop application through AIR Gamepad Notifications. The "mag" property in the notification is an array containing the X, Y, Z coordinate values of the magnetic field in microtesla (μT), along with the millisecond epoch time when the event was generated. The coordinate space of the magnetometer events has the origin at the center of the landscape oriented screen, with the X axis pointing from left to right, Y axis from bottom to top, and the Z axis pointing out of the screen, towards the user.


The magnetometer events will be sent by AIR Gamepad to the desktop application as AIR Gamepad Notifications with the following structure:

{
"header" : {
"title" : " MAGNETOMETER_EVENT",
"timestamp" : <A number value holding the millisecond epoch time when the notification was created>,
"type" : "NOTIFICATION"
},
"data" : {
"notification" : {
"mag" : [
<A number value holding the X coordinate value of the magnetic field in μT>,
<A number value holding the Y coordinate value of the magnetic field in μT>,
<A number value holding the Z coordinate value of the magnetic field in μT>,
<A number value holding the millisecond epoch time when the event was generated>
]
}
}
}

Gyroscope event task

A gyroscope event task can be executed to start or stop generating gyroscope events from the device, within the specified interval. Once the gyroscope event generation has been started, the rate of rotation detected by the device will be sent to the desktop application as AIR Gamepad notifications.


A gyroscope event task can be executed using the following AIR Gamepad Notification:

{
"header" : {
"title" : "GYROSCOPE_EVENT",
"timestamp" : <A number value holding the millisecond epoch time when the notification is created>,
"type" : "NOTIFICATION"
},
"data" : {
"notification" : {
"start" : <A boolean value indicating if the device should start generating the gyroscope events. Set it as true to start generating the events and false to stop generating the events>,
"interval" : <A number value indicating the millisecond interval in which the gyroscope events must be sent. The events may be received faster or slower than the specified interval>
}
}
}

Once the gyroscope event generation has been started, AIR Gamepad will be sending the gyroscope events to the desktop application through AIR Gamepad Notifications. The "gyro" property in the notification is an array containing the X, Y, Z coordinate values of the rate of rotation in radians per second (rad/s), along with the millisecond epoch time when the event was generated. The coordinate space of the gyroscope events has the origin at the center of the landscape oriented screen, with the X axis pointing from left to right, Y axis from bottom to top, and the Z axis pointing out of the screen, towards the user.


The gyroscope events will be sent by AIR Gamepad to the desktop application as AIR Gamepad Notifications with the following structure:

{
"header" : {
"title" : " GYROSCOPE_EVENT",
"timestamp" : <A number value holding the millisecond epoch time when the notification was created>,
"type" : "NOTIFICATION"
},
"data" : {
"notification" : {
"gyro" : [
<A number value holding the rate of rotation around the X axis in rad/s>,
<A number value holding the rate of rotation around the Y axis in rad/s>,
<A number value holding the rate of rotation around the Z axis in rad/s>,
<A number value holding the millisecond epoch time when the event was generated>
]
}
}
}

AIR Gamepad Error Logs and Error Handling

If an error occurs during AIR Gamepad connection establishment, or if AIR Gamepad faces any network error including unexpected network disconnection, or if the message sent over the network is too large for AIR Gamepad to process, the WebSocket server running in AIR Gamepad would close the connection with a WebSocket CloseEvent. As specified in WebSocket CloseEvent specification, the event would include information about whether the closing was clean, the close code and a reason string containing the reason for closing the connection.


In case an error occurred while interpreting a serialized AIR Gamepad message sent to the device (eg. the message can't be parsed, or if structure of an AIR Gamepad message is not as expected, or if an unsupported hardware functionality has been requested), AIR Gamepad would send an error log event to the desktop application. The error log events will be sent by AIR Gamepad to the desktop application as AIR Gamepad Notifications with the following structure:

{
"header" : {
"title" : "ERROR_LOG",
"timestamp" : <A number value holding the millisecond epoch time when the notification was created>,
"type" : "NOTIFICATION"
},
"data" : {
"notification" : {
"message" : <A string value describing the error occurred>
}
}
}

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy