react-native-peripheral
React Native library for building BLE peripherals.
Note: If you want to write a BLE Central application (that connects to BLE peripherals such as a watch or heart rate monitor), check out react-native-ble-plx or react-native-ble-manager instead.
Installation
Using npm:
npm install --save react-native-peripheral
or using yarn:
yarn add react-native-peripheral
Then follow the instructions for your platform to link react-native-peripheral into your project:
iOS
React Native 0.60 and above
Linking is automatic. Just run pod install
in the ios
directory.
React Native 0.59 and below
Run react-native link react-native-peripheral
to link the react-native-peripheral library.
If you're still managing dependencies through Xcode projects, or if the above didn't work:
- In XCode, in the project navigator, right click
Libraries
➜Add Files to [your project's name]
- Go to
node_modules
➜react-native-peripheral
and addRnBlePeripheral.xcodeproj
- In XCode, in the project navigator, select your project. Add
libRnBlePeripheral.a
to your project'sBuild Phases
➜Link Binary With Libraries
- Run your project (
Cmd+R
)
Android
Android support is not implemented yet.
Usage
Peripheral
Note: addService
and startAdvertising
are conceptually independent events. A BLE peripheral can start advertising regardless of whether if has defined any services. Conversely, you can define services which can be used by previously defined clients. However, in most cases, you'll want to do both.
To end a session, you can call Peripheral.stopAdvertising
. You can also check if you're currently advertising with Periperheral.isAdvertising
.
Dynamic Value
If you want to change the characteristic value dynamically, instead of providing value
, implement onReadRequest
and onWriteRequest
(if your characteristic supports read
and write
operations):
uuid: '...' properties: 'read' 'write' permissions: 'readable' 'writeable' onReadRequest: async { const value = '...' // calculate the value return value // you can also return a promise } onWriteRequest: async { // store or do something with the value thisvalue = value }
Notifications
If the value in your characteristic changes frequently, BLE clients may want to subscribe to be notified about the changes. Subscription logic is handled for you automatically, you just need to do two things:
-
Include
notify
in the list of properties:const ch =// ...properties: 'notify' ... -
Trigger
notify
with a value to send to subscribed clients:const value = '...'ch -
(optional) You may also track when clients subscribe to notifications, for example to avoid recomputing the value when no one is listening. This is optional since a call to
notify
will deliver to all subscribers by default, and silently no-op when there are none.const listeners = 0const ch =// ...{listeners++;}{listerers--;}// sometime laterif listenersconst value = '...' // calculate valuech
Base64
This library expects the value to be a Base64-encoded string.
Depending on your use case, you may want to add a library to help you convert to Base64:
- If you work with binary data, we recommend you internally store an
ArrayBuffer
orUint8Array
and convert it using base64-arraybuffer or base64-js - For dealing with complex binary structures, try jBinary
- If you want to send text data, we recommend you use base64.js