Sensors - 传感器
<p>[TOC]</p>
<h1>Sensors</h1>
<blockquote>
<p>Stability: 2 - Stable</p>
</blockquote>
<p>sensors模块提供了获取手机上的传感器的信息的支持，这些传感器包括距离传感器、光线光感器、重力传感器、方向传感器等。需要指出的是，脚本只能获取传感器的数据，<strong>不能模拟或伪造传感器的数据和事件</strong>，因此诸如模拟摇一摇的功能是无法实现的。</p>
<p>要监听一个传感器时，需要使用<code>sensors.register()</code>注册监听器，之后才能开始监听；不需要监听时则调用<code>sensors.unregister()</code>注销监听器。在脚本结束时会自动注销所有的监听器。同时，这种监听会使脚本保持运行状态，如果不注销监听器，脚本会一直保持运行状态。</p>
<p>例如，监听光线传感器的代码为：</p>
<pre><code>//光线传感器监听
sensors.register("light").on("change", (event, light)=>{
log("当前光强度为", light);
});</code></pre>
<p>要注意的是，每个传感器的数据并不相同，所以对他们调用<code>on()</code>监听事件时的回调函数参数也不是相同，例如光线传感器参数为<code>(event, light)</code>，加速度传感器参数为<code>(event, ax, ay, az)</code>。甚至在某些设备上的传感器参数有所增加，例如华为手机的距离传感器为三个参数，一般手机只有一个参数。</p>
<p>常用的传感器及其事件参数如下表：</p>
<ul>
<li>
<p><code>accelerometer</code> 加速度传感器，参数<code>(event, ax, ay, az)</code>:</p>
<ul>
<li><code>event</code> <a href="#sensors_sensorevent">SensorEvent</a> 传感器事件，用于获取传感器数据变化时的所有信息</li>
<li><code>ax</code> {number} x轴上的加速度，单位m/s^2</li>
<li><code>ay</code> {number} y轴上的加速度，单位m/s^2</li>
<li><code>az</code> {number} z轴上的加速度，单位m/s^2
这里的x轴，y轴，z轴所属的坐标系统如下图(其中z轴垂直于设备屏幕表面):</li>
</ul>
<p>!<img src="#images/axis_device.png" alt="axis_device" /></p>
</li>
<li>
<p><code>orientation</code> 方向传感器，参数<code>(event, azimuth, pitch, roll)</code>:</p>
<ul>
<li><code>event</code> <a href="#sensors_sensorevent">SensorEvent</a> 传感器事件，用于获取传感器数据变化时的所有信息</li>
<li><code>azimuth</code> {number} 方位角，从地磁指北方向线起，依顺时针方向到y轴之间的水平夹角，单位角度，范围0~359</li>
<li><code>pitch</code> {number} 绕x轴旋转的角度，当设备水平放置时该值为0，当设备顶部翘起时该值为正数，当设备尾部翘起时该值为负数，单位角度，范围-180~180</li>
<li><code>roll</code> {number} 绕y轴顺时针旋转的角度，单位角度，范围-90~90</li>
</ul>
</li>
<li>
<p><code>gyroscope</code> 陀螺仪传感器，参数<code>(event, wx, wy, wz)</code>:</p>
<ul>
<li><code>event</code> <a href="#sensors_sensorevent">SensorEvent</a> 传感器事件，用于获取传感器数据变化时的所有信息</li>
<li><code>wx</code> {number} 绕x轴的角速度，单位弧度/s</li>
<li><code>wy</code> {number} 绕y轴的角速度，单位弧度/s</li>
<li><code>wz</code> {number} 绕z轴的角速度，单位弧度/s</li>
</ul>
</li>
<li>
<p><code>magnetic_field</code> 磁场传感器，参数<code>(event, bx, by, bz)</code>:</p>
<ul>
<li><code>event</code> <a href="#sensors_sensorevent">SensorEvent</a> 传感器事件，用于获取传感器数据变化时的所有信息</li>
<li><code>bx</code> {number} x轴上的磁场强度，单位uT</li>
<li><code>by</code> {number} y轴上的磁场强度，单位uT</li>
<li><code>bz</code> {number} z轴上的磁场强度，单位uT</li>
</ul>
</li>
<li>
<p><code>gravity</code> 重力传感器，参数<code>(event, gx, gy, gz)</code>:</p>
<ul>
<li><code>event</code> <a href="#sensors_sensorevent">SensorEvent</a> 传感器事件，用于获取传感器数据变化时的所有信息</li>
<li><code>gx</code> {number} x轴上的重力加速度，单位m/s^2</li>
<li><code>gy</code> {number} y轴上的重力加速度，单位m/s^2</li>
<li><code>gz</code> {number} z轴上的重力加速度，单位m/s^2</li>
</ul>
</li>
<li>
<p><code>linear_acceleration</code> 线性加速度传感器，参数<code>(event, ax, ay, az)</code>:</p>
<ul>
<li><code>event</code> <a href="#sensors_sensorevent">SensorEvent</a> 传感器事件，用于获取传感器数据变化时的所有信息</li>
<li><code>ax</code> {number} x轴上的线性加速度，单位m/s^2</li>
<li><code>ay</code> {number} y轴上的线性加速度，单位m/s^2</li>
<li><code>az</code> {number} z轴上的线性加速度，单位m/s^2</li>
</ul>
</li>
<li>
<p><code>ambient_temperature</code> 环境温度传感器，大部分设备并不支持，参数<code>(event, t)</code>:</p>
<ul>
<li><code>event</code> <a href="#sensors_sensorevent">SensorEvent</a> 传感器事件，用于获取传感器数据变化时的所有信息</li>
<li><code>t</code> {number} 环境温度，单位摄氏度。</li>
</ul>
</li>
<li>
<p><code>light</code> 光线传感器，参数<code>(event, light)</code>:</p>
<ul>
<li><code>event</code> <a href="#sensors_sensorevent">SensorEvent</a> 传感器事件，用于获取传感器数据变化时的所有信息</li>
<li><code>light</code> {number} 环境光强度，单位lux</li>
</ul>
</li>
<li>
<p><code>pressure</code> 压力传感器，参数<code>(event, p)</code>:</p>
<ul>
<li><code>event</code> <a href="#sensors_sensorevent">SensorEvent</a> 传感器事件，用于获取传感器数据变化时的所有信息</li>
<li><code>p</code> {number} 大气压，单位hPa</li>
</ul>
</li>
<li>
<p><code>proximity</code> 距离传感器，参数<code>(event, distance)</code>:</p>
<ul>
<li><code>event</code> <a href="#sensors_sensorevent">SensorEvent</a> 传感器事件，用于获取传感器数据变化时的所有信息</li>
<li><code>distance</code> {number} 一般指设备前置摄像头旁边的距离传感器到前方障碍物的距离，并且很多设备上这个值只有两种情况：当障碍物较近时该值为0，当障碍物较远或在范围内没有障碍物时该值为5</li>
</ul>
</li>
<li><code>relative_humidity</code> 湿度传感器，大部分设备并不支持，参数<code>(event, rh)</code>:
<ul>
<li><code>event</code> <a href="#sensors_sensorevent">SensorEvent</a> 传感器事件，用于获取传感器数据变化时的所有信息</li>
<li><code>rh</code> {number} 相对湿度，范围为0~100（百分比）</li>
</ul></li>
</ul>
<h2>sensors.register(sensorName[, delay])</h2>
<ul>
<li><code>sensorName</code> {string} 传感器名称，常用的传感器名称如上面所述</li>
<li><code>delay</code> {number} 传感器数据更新频率，可选，默认为<code>sensors.delay.normal</code>。可用的值如下：
<ul>
<li><code>sensors.delay.normal</code> 正常频率</li>
<li><code>sensors.delay.ui</code> 适合于用户界面的更新频率</li>
<li><code>sensors.delay.game</code> 适合于游戏的更新频率</li>
<li><code>sensors.delay.fastest</code> 最快的更新频率】</li>
</ul></li>
<li>返回 <a href="#sensors_sensoreventemitter">SensorEventEmiiter</a></li>
</ul>
<p>注册一个传感器监听并返回<a href="#sensors_sensoreventemitter">SensorEventEmitter</a>。</p>
<p>例如:</p>
<pre><code>console.show();
//注册传感器监听
var sensor = sensors.register("gravity");
if(sensor == null){
toast("不支持重力传感器");
exit();
}
//监听数据
sensor.on("change", (gx, gy, gz)=>{
log("重力加速度: %d, %d, %d", gx, gy, gz);
});</code></pre>
<p>可以通过delay参数来指定传感器数据的更新频率，例如：</p>
<pre><code>var sensor = sensors.register("gravity", sensors.delay.game);</code></pre>
<p>另外，如果不支持<code>sensorName</code>所指定的传感器，那么该函数将返回<code>null</code>；但如果<code>sensors.ignoresUnsupportedSensor</code>的值被设置为<code>true</code>, 则该函数会返回一个不会分发任何传感器事件的<a href="#sensors_sensoreventemitter">SensorEventEmitter</a>。</p>
<p>例如:</p>
<pre><code>sensors.ignoresUnsupportedSensor = true;
//无需null判断
sensors.register("gravity").on("change", (gx, gy, gz)=>{
log("重力加速度: %d, %d, %d", gx, gy, gz);
});</code></pre>
<p>更多信息，参见<a href="#sensors_sensoreventemitter">SensorEventEmitter</a>和<a href="#sensors_sensors_ignoresUnsupportedSensor">sensors.ignoresUnsupportedSensor</a>。</p>
<h2>sensors.unregister(emitter)</h2>
<ul>
<li><code>emiiter</code> <a href="#sensors_sensoreventemitter">SensorEventEmitter</a></li>
</ul>
<p>注销该传感器监听器。被注销的监听器将不再能监听传感器数据。</p>
<pre><code>//注册一个传感器监听器
var sensor = sensors.register("gravity");
if(sensor == null){
exit();
}
//2秒后注销该监听器
setTimeout(()=> {
sensors.unregister(sensor);
}, 2000);</code></pre>
<h2>sensors.unregisterAll()</h2>
<p>注销所有传感器监听器。</p>
<h2>sensors.ignoresUnsupportedSensor</h2>
<ul>
<li>{boolean}</li>
</ul>
<p>表示是否忽略不支持的传感器。如果该值被设置为<code>true</code>，则函数<code>sensors.register()</code>即使对不支持的传感器也会返回一个无任何数据的虚拟传感器监听，也就是<code>sensors.register()</code>不会返回<code>null</code>从而避免非空判断，并且此时会触发<code>sensors</code>的"unsupported_sensor"事件。</p>
<pre><code>//忽略不支持的传感器
sensors.ignoresUnsupportedSensor = true;
//监听有不支持的传感器时的事件
sensors.on("unsupported_sensor", function(sensorName){
toastLog("不支持的传感器: " + sensorName);
});
//随便注册一个不存在的传感器。
log(sensors.register("aaabbb"));</code></pre>
<h2>事件: 'unsupported_sensor'</h2>
<ul>
<li><code>sensorName</code> {string} 不支持的传感器名称</li>
</ul>
<p>当<code>sensors.ignoresUnsupportedSensor</code>被设置为<code>true</code>并且有不支持的传感器被注册时触发该事件。事件参数的传感器名称。</p>
<h1>SensorEventEmitter</h1>
<p>注册传感器返回的对象，其本身是一个EventEmmiter，用于监听传感器事件。</p>
<h2>事件: 'change'</h2>
<ul>
<li><code>..args</code> {Any} 传感器参数</li>
</ul>
<p>当传感器数据改变时触发该事件；该事件触发的最高频繁由<code>sensors.register()</code>指定的delay参数决定。</p>
<p>事件参数根据传感器类型不同而不同，具体参见本章最前面的列表。</p>
<p>一个监听光线传感器和加速度传感器并且每0.5秒获取一个数据并最终写入一个csv表格文件的例子如下：</p>
<pre><code>//csv文件路径
cosnt csvPath = "/sdcard/sensors_data.csv";
//记录光线传感器的数据
var light = 0;
//记录加速度传感器的数据
var ax = 0;
var ay = 0;
var az = 0;
//监听光线传感器
sensors.register("light", sensors.delay.fastest)
.on("change", l => {
light = l;
});
//监听加速度传感器
sensors.register("accelerometer", sensors.delay.fastest)
.on("change", (ax0, ay0, az0) => {
ax = ax0;
ay = ay0;
az = az0;
});
var file = open(csvPath, "w");
//写csv表格头
file.writeline("light,ax,ay,az")
//每0.5秒获取一次数据并写入文件
setInterval(()=>{
file.writeline(util.format("%d,%d,%d,%d", light, ax, ay, az));
}, 500);
//10秒后退出并打开文件
setTimeout(()=>{
file.close();
sensors.unregsiterAll();
app.viewFile(csvPath);
}, 10 * 1000);
</code></pre>
<h2>事件: 'accuracy_change'</h2>
<ul>
<li><code>accuracy</code> {number} 表示传感器精度。为以下值之一:
<ul>
<li>-1 传感器未连接</li>
<li>0 传感器不可读</li>
<li>1 低精度</li>
<li>2 中精度</li>
<li>3 高精度</li>
</ul></li>
</ul>
<p>当传感器精度改变时会触发的事件。比较少用。</p>