RingSDK is a powerful and easy-to-use SDK for integrating the Taika Ring into your applications. This SDK provides functionalities to control the ring, configure settings, and interact with other devices via BLE (Bluetooth Low Energy).
Before you begin, ensure you have met the following requirements:
- Node.js (>=12.x)
- npm (>=6.x)
- TypeScript (>=4.x)
To install the RingSDK in your existing React Native project, follow these steps:
- Install the RingSDK Package:
Make sure you are in the root of your project, then run:
npm install ring-sdk-react-native
cd ringsdk- iOS Only: Install CocoaPods Dependencies:
Change to the ios directory and install the CocoaPods dependencies:
cd ios
pod install
cd ..- Link Native Dependencies:
For React Native versions 0.60 and above, the native dependencies are linked automatically. For older versions, you might need to link manually.
- Set up Bluetooth permissions
If you project didn't use Bluetooth before adding RingSDK, you need to add Bluetooth usage permissions for the app.
To do this, follow the Setting Up Bluetooth Permissions section.
- Run the Project:
To run your React Native project with the integrated RingSDK, use the following command:
npx react-native run-ios --device "My Device Name" # For iOS
npx react-native run-android # For AndroidTo create a new React Native project and integrate the RingSDK, follow these steps:
- Initialize a New React Native Project:
npx react-native init myAppName
cd myAppName- Install the RingSDK Package:
npm install ring-sdk-react-native- iOS Only: Install CocoaPods Dependencies:
Change to the ios directory, install the CocoaPods dependencies, and configure Xcode for signing:
cd ios
pod install
open myAppName.xcworkspace In Xcode, click on myAppName in the project navigator, go to the Signing & Capabilities tab, and select your team for signing.
After configuring signing in Xcode, return to the root directory:
cd ..- Set up Bluetooth permissions
To use RingSDK in your new project, you need to add Bluetooth usage permissions for the app.
To do this, follow the Setting Up Bluetooth Permissions section.
- Run the Project:
To run your React Native project with the integrated RingSDK, use the following command:
npx react-native run-ios --device "My Device Name" # For iOS
npx react-native run-android # For AndroidIf your project didn't use Bluetooth before adding the RingSDK or you are creating a new project, you need to add Bluetooth usage permissions for the app. The RingSDK will handle asking for the permissions, but you need to set them up in the podfile and/or Android manifest.
-
Info.plist: Add the following entries to your
ios/MyAppName/Info.plistfile to request Bluetooth permissions.<key>NSBluetoothAlwaysUsageDescription</key> <string>We need access to Bluetooth to connect to the ring.</string> <key>NSBluetoothPeripheralUsageDescription</key> <string>We need access to Bluetooth to connect to the ring.</string> <key>NSLocationAlwaysUsageDescription</key> <string>We need access to your location to use Bluetooth.</string> <key>NSLocationWhenInUseUsageDescription</key> <string>We need access to your location to use Bluetooth.</string>
-
AndroidManifest.xml: Add the following permissions to your
android/app/src/main/AndroidManifest.xmlfile to request Bluetooth permissions.<uses-permission android:name="android.permission.BLUETOOTH" /> <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" /> <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /> <uses-permission android:name="android.permission.BLUETOOTH_SCAN" /> <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" /> <!-- Required for Bluetooth LE --> <uses-feature android:name="android.hardware.bluetooth_le" android:required="true"/>
-
Gradle Configuration: Ensure that your
android/build.gradleandandroid/app/build.gradlefiles are configured to use the correct SDK versions.In
android/build.gradle:buildscript { ext { buildToolsVersion = "30.0.3" minSdkVersion = 21 compileSdkVersion = 30 targetSdkVersion = 30 } }
In
android/app/build.gradle:android { compileSdkVersion rootProject.ext.compileSdkVersion defaultConfig { minSdkVersion rootProject.ext.minSdkVersion targetSdkVersion rootProject.ext.targetSdkVersion } }
For detailed setup instructions, follow the react-native-ble-plx setup guide for both iOS and Android.
Here’s a simplified example app that shows how to use the RingSDK to show live touch coordinates on the ring's touchpad.
import React, { useEffect, useState } from 'react';
import { SafeAreaView, Text } from 'react-native';
import { BleManager } from 'react-native-ble-plx';
import { initializeRing, onTouchEvent } from 'ring-sdk-react-native';
// Create a Bluetooth manager from the package react-native-ble-plx
const manager = new BleManager();
const App: React.FC = () => {
const [touchpadXValue, setTouchpadXValue] = useState('0.00');
const [touchpadYValue, setTouchpadYValue] = useState('0.00');
useEffect(() => {
const setupSDK = async () => {
// Initialize the ring by passing the Bluetooth manager to the initializer function
await initializeRing(manager);
console.log('Ring is initialized.');
};
setupSDK();
// Event handler for touch events
const handleTouchEvent = (data: any) => {
console.log('New touch data received:', data.x, data.y);
setTouchpadXValue(data.x.toFixed(2));
setTouchpadYValue(data.y.toFixed(2));
};
// Set the touch event callback
onTouchEvent(handleTouchEvent);
return () => {
// Destroy Bluetooth manager upon exit
manager.destroy();
};
}, []);
return (
<SafeAreaView style={styles.container}>
<Text style={styles.text}>Touchpad X: {touchpadXValue}</Text>
<Text style={styles.text}>Touchpad Y: {touchpadYValue}</Text>
</SafeAreaView>
);
};
const styles = {
container: {
flex: 1,
justifyContent: 'center',
alignItems: 'center',
},
text: {
fontSize: 18,
margin: 10,
},
};
export default App;- Bluetooth Manager: A Bluetooth manager is created using the react-native-ble-plx package.
- Initialization: The initializeRing function is used to initialize the ring and set up the necessary Bluetooth connections.
- State Management: The component maintains state for the touchpad values.
- Event Handlers: Event handlers are set up to handle touch events from the ring.
For more comprehensive examples and advanced usage, please refer to the example applications in the RingSDK GitHub repository.
Certainly! Here is the bitmask section formatted for your README file, along with an explanation on how it is used in the TouchData struct:
-
MotionData
interface MotionData { acc: Vector3; gyro: Vector3; mag: Vector3; orientationRelative: Vector4; orientationAbsolute: Vector4; }
-
Vector3
interface Vector3 { x: number; y: number; z: number; }
-
Vector4
interface Vector4 { x: number; y: number; z: number; w: number; }
-
TouchData
interface TouchData { touchActive: boolean; x: number; y: number; touchStrength: number; timestamp: number; touchpadEventMask: TouchEventMask; }
The TouchEventMask is a bitmask that represents various touch events. Bitmasks allow us to represent multiple boolean flags in a single number, with each bit in the number representing a different flag.
export enum TouchEvent {
TOUCH_ACTIVE = 1 << 0, // 1st bit, hexadecimal 1
TOUCH_START = 1 << 1, // 2nd bit, hexadecimal 2
TOUCH_END = 1 << 2, // 3rd bit, hexadecimal 4
TOUCH_TOP = 1 << 3, // 4th bit, hexadecimal 8 (0x00000008)
TOUCH_SIDE = 1 << 4, // 5th bit, hexadecimal 10 (0x00000010)
GESTURE_EVENT = 1 << 5, // 6th bit, hex 20
LOW_POWER_OUTPUT = 1 << 6, // 7th bit, hex 40
HOLD_START = 1 << 8, // 9th bit, hex 80
HOLD_RELEASE = 1 << 9, // 10th bit, hex 100
HOLD_ONGOING = 1 << 10, // 11th bit, hex 200
SINGLE_TAP = 1 << 11, // 12th bit, hex 400
DOUBLE_TAP = 1 << 12, // 13th bit
TRIPLE_TAP = 1 << 13, // 14th bit
SLOW_SWIPE_UP = 1 << 16, // 17th bit
SLOW_SWIPE_DOWN = 1 << 17, // 18th bit
SLOW_SWIPE_LEFT = 1 << 18, // 19th bit
SLOW_SWIPE_RIGHT = 1 << 19, // 20th bit
SWIPE_UP = 1 << 20, // 21st bit
SWIPE_DOWN = 1 << 21, // 22nd bit
SWIPE_LEFT = 1 << 22, // 23rd bit
SWIPE_RIGHT = 1 << 23, // 24th bit
PM_ACTIVE = 1 << 26, // 27th bit
PM_IDLE = 1 << 27, // 28th bit
PM_LOW_POWER = 1 << 28, // 29th bit
PM_TO_ACTIVE = 1 << 29, // 30th bit
PM_TO_IDLE = 1 << 30, // 31st bit
PM_TO_LOW_POWER = 1 << 31 // 32nd bit
}
export type TouchEventMask = number;In the TouchData struct, the touchpadEventMask field uses the TouchEventMask type to represent various touch events using a bitmask. This allows multiple touch events to be captured and represented in a single number. For example, if multiple touch events occur simultaneously, they can be combined using the bitwise OR operator (|), and individual events can be checked using the bitwise AND operator (&).
To set multiple touch events, combine them using the bitwise OR operator (|):
let events: TouchEventMask = TouchEvent.TOUCH_START | TouchEvent.SINGLE_TAP | TouchEvent.SWIPE_UP;To check if a specific touch event is set, use the bitwise AND operator (&):
if (events & TouchEvent.SINGLE_TAP) {
// Single tap event is set
}We welcome contributions!
If you would like to contribute to the RingSDK, please fork the repository and create a pull request with your changes.
Please see our CONTRIBUTING.md for more details on supporting our work.
This software is licensed under dual licensing terms:
- MIT License: This license allows for free use, modification, and distribution of the Software for following use cases:
- when used with Taika Tech Oy's smart rings,
- when used for personal use,
- when used for educational use.
See the LICENSE file for the full text of the MIT License.
- Taika Software License 1 (TSL1): This license applies to the use of the Software with other manufacturers' smart rings, or other typically finger-worn or wrist-worn devices, and requires a separate commercial license from Taika Tech Oy. Contact [email protected] to acquire such a license.
See the COMMERCIAL_LICENSE file for the full text of the TSL1.
If you have any questions or need further assistance, please contact
- [email protected] for development related questions and feedback
- [email protected] for general inquiries