# ohos-beacon-library

**Repository Path**: openharmony-sig/ohos-beacon-library

## Basic Information

- **Project Name**: ohos-beacon-library
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 6
- **Forks**: 16
- **Created**: 2022-04-16
- **Last Updated**: 2025-06-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ohos_beacon_library 

## 简介

> 蓝牙工具，主要涉及信标区域监控以及信标设备测距

## 效果展示

![img](image/screen.png)

## 下载安装

```shell
ohpm install @ohos/beacon-library 
```

OpenHarmony
npm环境配置等更多内容，请参考 [如何安装OpenHarmony ohpm包](https://gitee.com/openharmony-tpc/docs/blob/master/OpenHarmony_har_usage.md) 。

## 使用说明

### 信标组件使用样例

1.在page页面中引入信标库必要的文件

```
import { Identifier, Region, BeaconParser, BeaconManager, RangeNotifier,Beacon } from '@ohos/beacon-library'
import bluetooth from '@ohos.bluetooth.ble';
```

2.使用

```
- 启动测距
_this.beaconManager.addRangeNotifier(new class implements RangeNotifier {
    didRangeBeaconsInRegion(beacons: Array<Beacon>, region: Region): void {
        _this.beaconList = beacons
    }
});
_this.beaconManager.startRangingBeacons(region);

- 停止测距
this.beaconManager.stopRangingBeacons(new Region("myRangingUniqueId", null, null, null));

- 启动监控
_this.beaconManager.addMonitorNotifier(new class implements MonitorNotifier {
    INSIDE:number = 1
    OUTSIDE:number = 0

    didEnterRegion(region:Region):void {
        _this.enterRegionText = "I just saw a region: " + region.getUniqueId()
    }
    
    didExitRegion(region:Region):void {
        _this.enterRegionText = "I no longer see an beacon in Region:" + region.getUniqueId()
    }
    
    didDetermineStateForRegion(state:number, region:Region):void {
        _this.determineStateText = "I have just switched from seeing/not seeing beacons: " + state
    }
});
_this.beaconManager.startMonitoring(region);

- 停止监控
this.beaconManager.stopMonitoring(new Region("myMonitorUniqueId", null, null, null));
```

## 接口说明

`@State private beaconManager: BeaconManager = BeaconManager.getInstanceForApplication()`

1. 当扫描到信标时的监控通知处理接口
   `.beaconManager.addMonitorNotifier(notifier:MonitorNotifier): void`
2. 开启信标监控，查找匹配region的beacons
   `.beaconManager.startMonitoring(region:Region ):void`
3. 当扫描到信标时的距离通知处理接口
   `.beaconManager.addRangeNotifier(notifier:RangeNotifier):void`
4. 开启信标距离测算
   `.beaconManager.startRangingBeacons(region:Region):void`
5. 为信标解释器指定编码规则
   `new BeaconParser().setBeaconLayout（beaconLayout:String）:void `
6. 将常见的数据类型封装为一个Identifier类型。
   `Identifier.parse（stringValue:String, desiredByteLength?:number）:Identifier`
7. 根据uniqueId与其它参数的组合，构造匹配信标的字段条件。
   `Region(uniqueId: string, id1?: Identifier, id2?: Identifier, id3?: Identifier, identifiers?: Array<Identifier>, bluetoothAddress?: string)`

## 约束与限制

在下述版本验证通过：
- DevEco Studio 版本： 4.1 Canary(4.1.3.317)

- OpenHarmony SDK:API11 (4.1.0.36)

## 目录结构

````
|---- ohos_beacon_library  
|     |---- entry  # 示例代码文件夹
|     |---- library # beacon库
|	      |----src
|             |----main
|                 |----ets
|                     |----components
|                         |---- beacon # beacon库文件夹
|                             |---- client #客户端三种情况数据处理
|                             |---- distance 设备相关设置及距离配置逻辑
|                             |---- logging #日志相关逻辑
|                             |---- service #服务端处理逻辑
|                             |---- simulator #信标计算
|                             |---- startup #数据发送与接收
|                             |---- utils #工具类
|                             |---- AltBeacon.ets #建立信标通信
|                             |---- BeaconParser.ets #beacon数据包解析
|                         |---- bluetooth      # 蓝牙库
|                             |---- BleAdvertisement.ets #信标广播逻辑
|                             |---- Pdu.ets #蓝牙数据传递单元
|     |---- README.md  # 安装使用方法                    
````

## 关于混淆
- 代码混淆，请查看[代码混淆简介](https://docs.openharmony.cn/pages/v5.0/zh-cn/application-dev/arkts-utils/source-obfuscation.md)
- 如果希望beacon-library库在代码混淆过程中不会被混淆，需要在混淆规则配置文件obfuscation-rules.txt中添加相应的排除规则：

```
-keep
./oh_modules/@ohos/beacon-library
```

## 贡献代码

使用过程中发现任何问题都可以提 [Issue](https://gitee.com/openharmony-sig/ohos-beacon-library/issues)给组件，当然，也非常欢迎发 [PR](https://gitee.com/openharmony-sig/ohos-beacon-library/pulls) 共建。

## 开源协议

本项目基于 [Apache License 2.0](https://gitee.com/openharmony-sig/ohos-beacon-library/blob/master/LICENSE) ，请自由地享受和参与开源。