The 1Sheeld SDK for Android is a library that allows you to scan, connect and interact with 1Sheeld boards through your custom Android app. The SDK is compatible with Android 2.3 or above and requires devices with Bluetooth connectivity.
It allows you to:
- Scan for 1Sheelds (either classic or plus).
- Connect to multiple 1Sheelds at once, up to seven different ones. (either classic or plus)
- Send, receive and broadcast raw data and frames.
- Test, rename and change the communications baud rate of the connected boards.
- Update firmware.
In Addition to:
- Automatic connection retry in case of connection failure with 3 different approaches.
- Query Arduino library and firmware versions.
- Knowing if the received frame is one of the known shields frames.
- Control digital pins status and read their values.
- Send and receive raw bytes.
- Mute and Unmute communication with 1Sheeld.
- Broadcast frames of raw data to multiple devices at once.
- Queue frames in case Arduino is in a callback.
...and more.
IMPORTANT: By default, this library will only connect to Bluetooth devices that has 1Sheeld in its name.
Make sure JCenter is added to your project gradle.build file's list of repositories. (It is added by default for new projects created with the latest version of Android Studio)
repositories {
jcenter()
}to use the JCenter repository, add the following line to the dependencies section of your module's build.gradle.
dependencies {
...
compile 'com.integreight.onesheeld:sdk:2.2.0'
...
}You can replace 2.2.0 with the version you wish to use. (Review the releases page to know the version numbers of the old releases.)
Then initialize the SDK in the onCreate() method of your application class or main activity.
// Pass the context to the init method.
OneSheeldSdk.init(applicationContext);
// Optional, enable debugging messages.
OneSheeldSdk.setDebugging(true);Here is an example that scan, connect to the first found device, and controls its digital pins.
// Init the SDK with context
OneSheeldSdk.init(this);
// Optional, enable debugging messages.
OneSheeldSdk.setDebugging(true);
// Get the manager instance
OneSheeldManager manager = OneSheeldSdk.getManager();
// Set the connection failing retry count to 1
manager.setConnectionRetryCount(1);
// Set the automatic connecting retries to true, this will use 3 different methods for connecting
manager.setAutomaticConnectingRetriesForClassicConnections(true);
// Construct a new OneSheeldScanningCallback callback and override onDeviceFind method
OneSheeldScanningCallback scanningCallback = new OneSheeldScanningCallback() {
@Override
public void onDeviceFind(OneSheeldDevice device) {
// Cancel scanning before connecting
OneSheeldSdk.getManager().cancelScanning();
// Connect to the found device
device.connect();
}
};
// Construct a new OneSheeldConnectionCallback callback and override onConnect method
OneSheeldConnectionCallback connectionCallback = new OneSheeldConnectionCallback() {
@Override
public void onConnect(OneSheeldDevice device) {
// Output high on pin 13
device.digitalWrite(13,true);
// Read the value of pin 12
boolean isHigh=device.digitalRead(12);
}
};
// Add the connection and scanning callbacks
manager.addConnectionCallback(connectionCallback);
manager.addScanningCallback(scanningCallback);
// Initiate the Bluetooth scanning
manager.scan();
The sample application allows you to:
- Scan, and connect to multiple 1Sheeld devices at once.
- Control each device digital pins.
- Simulate the push button shield of the official app and send/broadcast its on/off frames.
- Query and change the board’s communications baud rate.
- Send and receive serial data.
- Rename the board with a random name.
- Test the board, both firmware and library.
- Update firmware from a set of preloaded firmwares.
The repo is a generic Gradle project, it was built and tested using the latest stable version of Android Studio.
To build the project and generate the release and debug aar(s), run this command on the root of the repo:
.\gradlew assemble
android.permission.BLUETOOTH: Required for connecting and communicating with paired Bluetooth devices.
android.permission.BLUETOOTH_ADMIN: Required for discovering and pairing Bluetooth devices.
android.permission.ACCESS_COARSE_LOCATION: Required for Bluetooth discovery starting from Android 6.0 (Android SDK v23).
The first two permissions are implicitly added for you when you include the SDK in your project, you don't have to add them to your manifest. The last one you have to both put it in your app's manifest and explicitly ask the user to grant it before scanning (An example of that is shown in the sample application).
Contributions are welcomed, please follow this pattern:
- Fork the repo.
- Open an issue with your proposed feature or bug fix.
- Commit and push code to a new branch in your forked repo.
- Submit a pull request to our development branch.
Don't forget to drop us an email, post on our forum, or mention us on Twitter or Facebook about what you have did with the SDK, we would love to hear about it.
- JavaDoc documentation.
- Play with Our Sample SDK App
- Download 1Sheeld App from Play Store.
- Check our 1Sheeld Forums where you can post your questions and get answers.
To see what has changed in recent versions of 1Sheeld Android SDK, see the Change Log.
This code is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License version 3 only, as
published by the Free Software Foundation.
This code is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
version 3 for more details (a copy is included in the LICENSE file that
accompanied this code).
Please contact Integreight, Inc. at [email protected] or post on our
support forums www.1sheeld.com/forum if you need additional information
or have any questions.