Learn how to use Bluetooth ANE in your Adobe Air mobile project
When you are looking for a multiplayer solution for your game (or your app), it means you need instant communication between devices. To make that happen, you have to consider the distance range of players first. If players are a few meters away from each other, the easiest and fastest way to connect them together is by using Bluetooth ANE.
You may also consider local network connection via WiFi using P2P technology. Although we will talk about P2P connections in another tutorial, you still need to think of an alternative in case players are not connected to a same WiFi network or even maybe they are not connected to any WiFi at all. In that case, keeping your game still playable requires something that you are 100% sure all devices have it. So, in this tutorial, I will tell you what exact steps you need to take to make Bluetooth connection between two devices and send data back and forth. Before we begin, checkout this video. By the end of this post, you will build this demo app. It’s cool, isn’t it?
Step 1) Implementing the Bluetooth ANE into your project
As you know already, Adobe Air does not have access to many hardware features on mobile devices so you defiantly need an ANE (Air Native Extension) to do the job for you. I presume you already have downloaded the Bluetooth Air Native Extension package. If not, you may consider getting it now. The aim of this tutorial is not to teach you how to implement ANEs into your flash projects, so if it’s your first time using an ANE in your development, I think you should first read this post to understand ANEs in deep: http://help.adobe.com/en_US/air/build/WS597e5dadb9cc1e0253f7d2fc1311b491071-8000.html (don’t be scared though, you’ll be doing it in less than 5 minutes, nothing complicated at all!
Anyway, what we are going to concentrate here is to how you should setup your Air project .xml manifest file to make sure the Bluetooth ANE can correctly implemented into your app.
The first thing to remember is not to try running your app in the simulator. You will need a real device for this.
The second thing to remember is to always use the latest Air SDK. The Bluetooth ANE needs to run on at least Air SDK 15. So checkout your .xml manifest file to make sure of that.
Our current Bluetooth ANE works on Android devices only at the moment, so you need to tell your app that you need permissions to access the Bluetooth hardware as follow.
Your project must correctly recognize these classes. If it doesn’t, it means that you have not correctly embedded the .ane file into your setup! Return to step one and find the reason or checkout our GitHub repository for similar issues.
var _ex:Bluetooth = new Bluetooth();
After initializing the extension, you should add listeners for several different Bluetooth activities but before we do that, I’d like to talk about the steps that the Bluetooth hardware takes to make two devices connected to each other.
Imagine the two apps in the above video clip. The first thing your app should do is to tell the Bluetooth hardware to start scanning for discovering another device. It usually takes a few seconds for Bluetooth to finish its scanning job. If it finds another device, it will dispatch the results. Every dispatched result includes the MAC address of the found device. This MAC address is of type String and you will use it to connect to the found device. But before that, you need to check if these two devices are already paired with each other or not. If they are paired before, you will use the MAC address to connect to the found device but if they are not paired, you will ask the Bluetooth hardware to pair the devices.
After all, you will wait till the extension tells you that the two devices are connected to each other. Now is the time to start sending messages between the two devices. Just remember that the max packet byte you are allowed to send at a time is 20 bytes. Don’t be disappointed though. You can send anything with any size over this Bluetooth connection. You just need to handle the transfer yourself. Maybe we’ll talk about this file transferring thing in another post, but for our current tutorial, we are going to send over just x and y positions.
So, let’s put all these talks to code. Read the comments in between.
var _ex:Bluetooth = new Bluetooth();
// dispatches the state of Bluetooth whenever it changes (you will know if it's on or off)
_ex.addEventListener(BluetoothEvent.BLUETOOTH_STATE , bluetoothState);
// dispatches the communication state of two devices
_ex.addEventListener(BluetoothEvent.COMMUNICATION_STATUS , communication);
// dispatches the connection state of two devices. Are the devices connected or not.
_ex.addEventListener(BluetoothEvent.CONNECTION , connection);
// dispatches the 'enable' and 'visibility' dialog states
_ex.addEventListener(BluetoothEvent.DIALOG_STATUS , dialog);
// dispatches the device discovering state
_ex.addEventListener(BluetoothEvent.DISCOVERING_STATUS , discovering);
// dispatches when new devices are discovered
_ex.addEventListener(BluetoothEvent.NEW_DISCOVERD , newDiscoverd);
// dispatches whenever a new String message is received from the other device
_ex.addEventListener(BluetoothEvent.READ_MESSAGE , readMessage);
// dispatches to notify you about the scan mode of the device
_ex.addEventListener(BluetoothEvent.SCAN_MODE , scanMode);
// dispatches when a String message is sent to the other device
_ex.addEventListener(BluetoothEvent.SEND_MESSAGE , sendMessage);
// check if Bluetooth hardware is on or off
if (_ex.isEnable)
{
// make Bluetooth visible to others infinitely
// or set a duration which must be between 0 and 3600
_ex.visible(0);
// start the communication service for Bluetooth
_ex.initCommunicationService();
}
else
{
// if it's not on, just turn it on
_ex.enable();
}
// listen to know when the Bluetooth is turning on
function bluetoothState(e:BluetoothEvent):void
{
trace("state >> " + e.param);
if (e.param == "bluetoothOn")
{
// as soon as it's on, make it visible and start the communication service
_ex.visible(0);
_ex.initCommunicationService();
}
}
Alright, up to here, you know you have the Bluetooth service on your device, on and it’s ready for communication. now is the time to tell the extension to start scanning for finding other devices. _ex.startDiscovery(); and when you do that, you need to listen to BluetoothEvent.DISCOVERING_STATUS event.
function discovering(e:BluetoothEvent):void
{
// this listener will help you know when scanning starts and when
// it finishes. you can force quite scanning if you wish but calling
// _ex.stopDiscovery(); method
if (e.param == "discoveringStarted")
{
trace("Scaning...");
}
else if (e.param == "discoveringFinished")
{
trace("Scan finished");
}
}
So, while scanning is in progress, you should also listen for BluetoothEvent.NEW_DISCOVERD to find details about the found devices.
function newDiscoverd(e:BluetoothEvent):void
{
var obj:Object = e.param;
trace("newDiscoverd >> " + "device = " + obj.device + " mac :" + obj.mac);
// check if we are paired with the found device or not?
var pairList:Array = _ex.pairedList;
var currDevice:Object;
for (var i:int = 0; i < pairList.length; i++)
{
currDevice = pairList[i];
if (currDevice.mac == obj.mac)
{
trace("you are paired to " + obj.mac)
}
}
}
As you see above, as soon as we find a new device, we must check if our device is already paired with the found device or not. because only if you are paired, you can call _ex.connectTo(mac); to connect to the device. otherwise, if you really want to connect to the device, you should first pair with it, so you should call _ex.pairWith(mac);
Alright, so, you are now trying to connect to the second device. you will find these two listeners very helpful. they will let you know when the connection is fully established or will notify you if the connection fails or disrupts.
function communication(e:BluetoothEvent):void
{
trace("communication >> " + e.param);
if (e.param == "connecting")
{
trace("connecting to the device...");
}
else if (e.param == "connected")
{
trace("CONNECTED");
}
}
function connection(e:BluetoothEvent):void
{
trace("connection >> " + e.param);
if (e.param == "connectionLost")
{
trace("connection lost!");
}
}
After you made sure the two device are connected to each other successfully, you can use the _ex.sendMessage(“my message from A to B!”); method to send a String message from one device to another. and of course you should listen to the BluetoothEvent.READ_MESSAGE event to know when a new message is being received on device B.
function readMessage(e:BluetoothEvent):void
{
trace("readMessage >> " + e.param);
}
As a side note, you might need to check and verify when device A is actually sending out the message. for that reason, you will have to listen to this event. BluetoothEvent.SEND_MESSAGE
That’s pretty much all 🙂 before you know it, you are actually transmitting information from one device to another. but before we finish this post, I’d like to warn you that be careful not to call the extension methods carelessly while developing! if you are on older Android devices, calling the methods randomly in development phase, will make your phone act weird and it won’t be fixed until you restart your device! I remember the Android team while they were developing the extension… they were restarting all the devices around them every two minutes! :)) we finally have a VERY stable Bluetooth Extension finally and I hope you will enjoy the result of many hours of developing and debugging on the Java side.
Oops, I almost forgot! when you are closing down your app, you MUST make sure you are disposing the extension._ex.dispose();
How to build multiplayer games in Adobe Air mobile (using Bluetooth ANE)
Learn how to use Bluetooth ANE in your Adobe Air mobile project
When you are looking for a multiplayer solution for your game (or your app), it means you need instant communication between devices. To make that happen, you have to consider the distance range of players first. If players are a few meters away from each other, the easiest and fastest way to connect them together is by using Bluetooth ANE.
You may also consider local network connection via WiFi using P2P technology. Although we will talk about P2P connections in another tutorial, you still need to think of an alternative in case players are not connected to a same WiFi network or even maybe they are not connected to any WiFi at all. In that case, keeping your game still playable requires something that you are 100% sure all devices have it. So, in this tutorial, I will tell you what exact steps you need to take to make Bluetooth connection between two devices and send data back and forth. Before we begin, checkout this video. By the end of this post, you will build this demo app. It’s cool, isn’t it?
Step 1) Implementing the Bluetooth ANE into your project
As you know already, Adobe Air does not have access to many hardware features on mobile devices so you defiantly need an ANE (Air Native Extension) to do the job for you. I presume you already have downloaded the Bluetooth Air Native Extension package. If not, you may consider getting it now. The aim of this tutorial is not to teach you how to implement ANEs into your flash projects, so if it’s your first time using an ANE in your development, I think you should first read this post to understand ANEs in deep: http://help.adobe.com/en_US/air/build/WS597e5dadb9cc1e0253f7d2fc1311b491071-8000.html (don’t be scared though, you’ll be doing it in less than 5 minutes, nothing complicated at all!
Anyway, what we are going to concentrate here is to how you should setup your Air project .xml manifest file to make sure the Bluetooth ANE can correctly implemented into your app.
The first thing to remember is not to try running your app in the simulator. You will need a real device for this.
The second thing to remember is to always use the latest Air SDK. The Bluetooth ANE needs to run on at least Air SDK 15. So checkout your .xml manifest file to make sure of that.
Our current Bluetooth ANE works on Android devices only at the moment, so you need to tell your app that you need permissions to access the Bluetooth hardware as follow.
Then, you need to add the following activity so your app can manage Bluetooth hardware.
And finally, you need to tell the Air compiler to compile the Bluetooth ANE like this.
Step 2) Initializing the Bluetooth ANE
To initialize the extension, you should first import the required classes.
Your project must correctly recognize these classes. If it doesn’t, it means that you have not correctly embedded the .ane file into your setup! Return to step one and find the reason or checkout our GitHub repository for similar issues.
After initializing the extension, you should add listeners for several different Bluetooth activities but before we do that, I’d like to talk about the steps that the Bluetooth hardware takes to make two devices connected to each other.
Imagine the two apps in the above video clip. The first thing your app should do is to tell the Bluetooth hardware to start scanning for discovering another device. It usually takes a few seconds for Bluetooth to finish its scanning job. If it finds another device, it will dispatch the results. Every dispatched result includes the MAC address of the found device. This MAC address is of type String and you will use it to connect to the found device. But before that, you need to check if these two devices are already paired with each other or not. If they are paired before, you will use the MAC address to connect to the found device but if they are not paired, you will ask the Bluetooth hardware to pair the devices.
After all, you will wait till the extension tells you that the two devices are connected to each other. Now is the time to start sending messages between the two devices. Just remember that the max packet byte you are allowed to send at a time is 20 bytes. Don’t be disappointed though. You can send anything with any size over this Bluetooth connection. You just need to handle the transfer yourself. Maybe we’ll talk about this file transferring thing in another post, but for our current tutorial, we are going to send over just x and y positions.
So, let’s put all these talks to code. Read the comments in between.
var _ex:Bluetooth = new Bluetooth(); // dispatches the state of Bluetooth whenever it changes (you will know if it's on or off) _ex.addEventListener(BluetoothEvent.BLUETOOTH_STATE , bluetoothState); // dispatches the communication state of two devices _ex.addEventListener(BluetoothEvent.COMMUNICATION_STATUS , communication); // dispatches the connection state of two devices. Are the devices connected or not. _ex.addEventListener(BluetoothEvent.CONNECTION , connection); // dispatches the 'enable' and 'visibility' dialog states _ex.addEventListener(BluetoothEvent.DIALOG_STATUS , dialog); // dispatches the device discovering state _ex.addEventListener(BluetoothEvent.DISCOVERING_STATUS , discovering); // dispatches when new devices are discovered _ex.addEventListener(BluetoothEvent.NEW_DISCOVERD , newDiscoverd); // dispatches whenever a new String message is received from the other device _ex.addEventListener(BluetoothEvent.READ_MESSAGE , readMessage); // dispatches to notify you about the scan mode of the device _ex.addEventListener(BluetoothEvent.SCAN_MODE , scanMode); // dispatches when a String message is sent to the other device _ex.addEventListener(BluetoothEvent.SEND_MESSAGE , sendMessage); // check if Bluetooth hardware is on or off if (_ex.isEnable) { // make Bluetooth visible to others infinitely // or set a duration which must be between 0 and 3600 _ex.visible(0); // start the communication service for Bluetooth _ex.initCommunicationService(); } else { // if it's not on, just turn it on _ex.enable(); } // listen to know when the Bluetooth is turning on function bluetoothState(e:BluetoothEvent):void { trace("state >> " + e.param); if (e.param == "bluetoothOn") { // as soon as it's on, make it visible and start the communication service _ex.visible(0); _ex.initCommunicationService(); } }Alright, up to here, you know you have the Bluetooth service on your device, on and it’s ready for communication. now is the time to tell the extension to start scanning for finding other devices. _ex.startDiscovery(); and when you do that, you need to listen to BluetoothEvent.DISCOVERING_STATUS event.
function discovering(e:BluetoothEvent):void { // this listener will help you know when scanning starts and when // it finishes. you can force quite scanning if you wish but calling // _ex.stopDiscovery(); method if (e.param == "discoveringStarted") { trace("Scaning..."); } else if (e.param == "discoveringFinished") { trace("Scan finished"); } }So, while scanning is in progress, you should also listen for BluetoothEvent.NEW_DISCOVERD to find details about the found devices.
function newDiscoverd(e:BluetoothEvent):void { var obj:Object = e.param; trace("newDiscoverd >> " + "device = " + obj.device + " mac :" + obj.mac); // check if we are paired with the found device or not? var pairList:Array = _ex.pairedList; var currDevice:Object; for (var i:int = 0; i < pairList.length; i++) { currDevice = pairList[i]; if (currDevice.mac == obj.mac) { trace("you are paired to " + obj.mac) } } }As you see above, as soon as we find a new device, we must check if our device is already paired with the found device or not. because only if you are paired, you can call _ex.connectTo(mac); to connect to the device. otherwise, if you really want to connect to the device, you should first pair with it, so you should call _ex.pairWith(mac);
Alright, so, you are now trying to connect to the second device. you will find these two listeners very helpful. they will let you know when the connection is fully established or will notify you if the connection fails or disrupts.
function communication(e:BluetoothEvent):void { trace("communication >> " + e.param); if (e.param == "connecting") { trace("connecting to the device..."); } else if (e.param == "connected") { trace("CONNECTED"); } } function connection(e:BluetoothEvent):void { trace("connection >> " + e.param); if (e.param == "connectionLost") { trace("connection lost!"); } }After you made sure the two device are connected to each other successfully, you can use the _ex.sendMessage(“my message from A to B!”); method to send a String message from one device to another. and of course you should listen to the BluetoothEvent.READ_MESSAGE event to know when a new message is being received on device B.
function readMessage(e:BluetoothEvent):void { trace("readMessage >> " + e.param); }As a side note, you might need to check and verify when device A is actually sending out the message. for that reason, you will have to listen to this event. BluetoothEvent.SEND_MESSAGE
That’s pretty much all 🙂 before you know it, you are actually transmitting information from one device to another. but before we finish this post, I’d like to warn you that be careful not to call the extension methods carelessly while developing! if you are on older Android devices, calling the methods randomly in development phase, will make your phone act weird and it won’t be fixed until you restart your device! I remember the Android team while they were developing the extension… they were restarting all the devices around them every two minutes! :)) we finally have a VERY stable Bluetooth Extension finally and I hope you will enjoy the result of many hours of developing and debugging on the Java side.
Oops, I almost forgot! when you are closing down your app, you MUST make sure you are disposing the extension._ex.dispose();
Share this:
Related