You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+85-98
Original file line number
Diff line number
Diff line change
@@ -1,143 +1,160 @@
1
1
# LIS3DH 3-Axis Accelerometer
2
2
3
-
The [LIS3DH](http://www.st.com/st-web-ui/static/active/en/resource/technical/document/datasheet/CD00274221.pdf) is a 3-Axis MEMS accelerometer. This sensor has extensive functionality and this class has not yet implemented all of it.
3
+
The [LIS3DH](http://www.st.com/st-web-ui/static/active/en/resource/technical/document/datasheet/CD00274221.pdf) is a 3-Axis MEMS accelerometer. The LIS3DH application note can be found [here](http://www.st.com/web/en/resource/technical/document/application_note/CD00290365.pdf). This sensor has extensive functionality and this class has not yet implemented all of it.
4
4
5
5
The LPS25H can interface over I²C or SPI. This class addresses only I²C for the time being.
6
6
7
-
**To add this library to your project, add**`#require "LIS3DH.class.nut:1.0.3"`**to the top of your device code**
7
+
**To add this library to your project, add**`#require "LIS3DH.class.nut:1.0.4"`**to the top of your device code**
8
8
9
9
## Class Usage
10
10
11
-
### constructor(*i2c[, addr]*)
12
-
13
-
The class’ constructor takes one required parameter (a configured imp I²C bus) and an optional parameter (the I²C address of the accelerometer):
11
+
### Constructor: LIS3DH(*i2cBus[, i2cAddress]*)
14
12
13
+
The class’ constructor takes one required parameter (a configured imp I²C bus) and an optional parameter (the I²C address of the accelerometer). The I²C address must be the address of your sensor or an I²C error will be thrown.
|*i2c*| hardware.i2c | N/A | A pre-configured I²C bus |
19
-
|*addr*| byte | 0x30 | The I²C address of the accelerometer |
17
+
|*i2cBus*| hardware.i2c | N/A | A pre-configured I²C bus |
18
+
|*i2cAddress*| byte | 0x30 | The I²C address of the accelerometer |
20
19
21
20
<br>
22
21
23
22
```squirrel
24
-
#require "LIS3DH.class.nut:1.0.3"
23
+
#require "LIS3DH.class.nut:1.0.4"
25
24
26
25
i2c <- hardware.i2c89;
27
26
i2c.configure(CLOCK_SPEED_400_KHZ);
28
27
29
-
accel <- LIS3DH(i2c, 0x32); // using a non-default I2C address (SA0 pulled high)
28
+
// Use a non-default I2C address (SA0 pulled high)
29
+
accel <- LIS3DH(i2c, 0x32);
30
30
```
31
31
32
32
## Class Methods
33
33
34
34
### init()
35
35
36
-
The *init()* method resets all registers to datasheet default values. This can be very useful during active development as clicking ‘Build and Run’ will not reset the chip.
36
+
The *init()* method resets all control and interrupt registers to datasheet default values.
37
37
38
38
```squirrel
39
-
i2c <- hardware.i2c89;
40
-
i2c.configure(CLOCK_SPEED_400_KHZ);
41
-
42
39
accel <- LIS3DH(i2c, 0x32);
43
-
44
-
// ***REMOVE BEFORE GOING TO PRODUCTION***
45
-
accel.reset();
46
-
// ***************************************
40
+
accel.init();
47
41
```
48
42
49
43
### setDataRate(*rateHz*)
50
44
51
-
The *setDataRate()* method sets the Output Data Rate (ODR) of the accelerometer in Hz. The nearest supported data rate less than or equal to the requested rate will be used and returned. Supported datarates are 0 (Shutdown), 1, 10, 25, 50, 100, 200, 400, 1600 and 5000Hz.
45
+
The *setDataRate()* method sets the Output Data Rate (ODR) of the accelerometer in Hz. Supported datarates are 0 (Shutdown), 1, 10, 25, 50, 100, 200, 400, 1250 (Normal Mode only), 1600 (Low-Power Mode only), and 5000 (Low-Power Mode only) Hz. The requested data rate will be rounded up to the closest supported rate and the actual data rate will be returned.
46
+
47
+
The default data rate is 0 (Shutdown). To take a reading with *getAccel()* you must set a data rate greater than 0.
52
48
53
49
```squirrel
54
-
local rate = accel.setDataRate(100);
55
-
server.log(format("Accelerometer running at %d Hz",rate));
50
+
local rate = accel.setDataRate(90);
51
+
server.log(format("Accelerometer running at %dHz", rate));
52
+
// Displays 'Accelerometer running at 100Hz'
56
53
```
57
54
58
-
**Note** The datarate must be set before reading the accelerometer with *getAccel()*.
55
+
### setLowPower(*state*)
59
56
60
-
### getAccel(*[callback]*)
57
+
The *setLowPower()* method configures the device to run in low-power or normal mode. The method takes one boolean parameter, *state*. When *state* is `true`, low-power mode is enabled. When *state* is `false`, normal mode is enabled. Normal mode guarantees high resolution; low-power mode reduces the current consumption. Higher data rates only support specific modes. See *setDataRate()* for details.
61
58
62
-
The *getAccel()* method reads and returns the latest measurement from the accelerometer as a table (in Gs):
59
+
Normal mode is enabled by default.
60
+
61
+
```Squirrel
62
+
// Enable low-power mode
63
+
accel.setLowPower(true);
64
+
```
65
+
66
+
### enable([*state*])
67
+
68
+
The *enable()* method enables or disables all three axes on the accelerometer. The method takes an optional boolean parameter, *state*. By default *state* is set to `true` and the accelerometer is enabled. When *state* is `false`, the accelerometer will be disabled.
63
69
64
70
```squirrel
65
-
{ x: <xData>, y: <yData>, z: <zData> }
71
+
function goToSleep() {
72
+
imp.onidle(function() {
73
+
// Set data rate to 0 and disable the accelerometer to save power
74
+
accel.setDataRate(0);
75
+
accel.enable(false);
76
+
77
+
// Sleep for 1 hour
78
+
server.sleepfor(3600);
79
+
});
80
+
}
66
81
```
67
82
83
+
### getAccel(*[callback]*)
84
+
85
+
The *getAccel()* method reads the latest measurement from the accelerometer. The method takes an optional callback for asynchronous operation — it will block otherwise. The callback should take one parameter: a results table *(see below)*. If the callback is null or omitted, the method will return the results table.
An optional callback (with a single parameter) can be passed to *getAccel()*. If a callback is included, the class will read the sensor data and pass the result to the callback method as the first parameter:
The *setRange()* method sets the measurement range of the sensor in Gs. Supported ranges are (±) 2, 4, 8 and 16G. The data rate will be rounded up to the closest supported range and the actual range will be returned.
94
113
95
-
The *setRange()* method sets the measurement range of the sensor in Gs. The default measurement range is ±2G. The nearest supported range less than or equal to the requested range will be used and returned. Supported ranges are (±) 2, 4, 6, 8 and 16G.
114
+
The default measurement range is ±2G.
96
115
97
116
```squirrel
98
-
// Set sensor range to +/- 6 G
99
-
local range = accel.setRange(6);
100
-
server.log(format("Range set to +/- %d G", range));
117
+
// Set sensor range to +/- 8G
118
+
local range = accel.setRange(8);
119
+
server.log(format("Range set to +/- %dG", range));
101
120
```
102
121
103
-
**Note** If you are not using the default ±2G range, you must set the range with *setRange()* before setting interrupt thresholds with *setInertialIntThreshold()* or *setClickIntThreshold()*.
104
-
105
122
### getRange()
106
123
107
124
The *getRange()* method returns the currently-set measurement range of the sensor in Gs.
108
125
109
126
```squirrel
110
-
server.log(format("Current Sensor Range is +/- %d G", accel.getRange()));
127
+
server.log(format("Current Sensor Range is +/- %dG", accel.getRange()));
The default configuration for the Intertial Interrupt generator is to generate an interrupt when the acceleration on *any* axis exceeds 1G. This behavior can be changed by OR-ing together any of the following flags:
147
+
The default configuration for the Intertial Interrupt generator is to generate an interrupt when the acceleration on *any* axis exceeds 2G. This behavior can be changed by OR'ing together any of the following flags:
131
148
132
-
|flag|description|
149
+
|Flag|Description|
133
150
| ------ | ----------- |
134
151
|*X_LOW*| Generates an interrupt when the x-axis acceleration goes below the threshold |
135
152
|*X_HIGH*| Generates an interrupt when the x-axis acceleration goes above the threshold |
136
153
|*Y_LOW*| Generates an interrupt when the y-axis acceleration goes below the threshold |
137
154
|*Y_HIGH*| Generates an interrupt when the y-axis acceleration goes above the threshold |
138
155
|*Z_LOW*| Generates an interrupt when the z-axis acceleration goes below the threshold |
139
156
|*Z_HIGH*| Generates an interrupt when the z-axis acceleration goes above the threshold |
140
-
|*AOI*| Sets the AOI flag *(see ‘Inertial Interrupt Modes’ below)*|
157
+
|*AOI *| Sets the AOI flag *(see ‘Inertial Interrupt Modes’ below)*|
141
158
|*SIX_D*| Sets the 6D flag *(see ‘Inertial Interrupt Modes’ below)*|
142
159
143
160
#### Inertial Interrupt Modes
@@ -157,7 +174,7 @@ The following is taken from the from [LIS3DH Datasheet](http://www.st.com/st-web
The *configureFreeFallInterrupt()* method configures the intertial interrupt generator to generate interrupts when the device is in free fall (acceleration on all axis appraoches 0). The default *threshold* is 0.5 Gs.The default *duration* is five samples.
177
+
The *configureFreeFallInterrupt()* method configures the intertial interrupt generator to generate interrupts when the device is in free fall (acceleration on all axis appraoches 0). The default *threshold* is 0.5G.The default *duration* is five samples.
Enables (*state* is `true`) or disables (*state* is `false`) Data Ready interrupts on the INT1 line.
214
+
Enables (*state* is `true`) or disables (*state* is `false`) data-ready interrupts on the INT1 line. The data-ready signal rises to 1 when a new set of acceleration data has been generated and it is available for reading. The interrupt is reset when the higher part of the data of all the enabled channels has been read.
Enables (*state* is `true`) or disables (*state* is `false`) interrupt latching. If interrupt latching is enabled, the interrupt signal will remain asserted until the interrupt source register is read by calling *getInterruptTable()*. If latching is disabled, the interrupt signal will remain asserted as long as the interrupt-generating condition persists.
207
224
208
-
Inertial and free fall are the only interrupts compatible with latching mode.
209
-
210
225
Interrupt latching is disabled by default.
211
226
212
227
*See sample code in getInterruptTable()*
213
228
214
229
### getInterruptTable()
215
230
216
-
The *getInterruptTable()* method reads the *INT1_SRC* and *CLICK_SRC* registers, and returns the result as a table with the following fields:
231
+
The *getInterruptTable()* method reads the LIS3DH’s *INT1_SRC* and *CLICK_SRC* registers, and returns the result as a table with the following fields:
217
232
218
233
```squirrel
219
234
{
@@ -230,7 +245,7 @@ The *getInterruptTable()* method reads the *INT1_SRC* and *CLICK_SRC* registers,
230
245
}
231
246
```
232
247
233
-
In the following example we setup an interrupt for doubleclick detection:
248
+
In the following example we setup an interrupt for double-click detection:
234
249
235
250
```squirrel
236
251
function interruptHandler() {
@@ -348,34 +363,6 @@ Returns the one-byte device ID of the sensor (from the *WHO_AM_I* register). The
0 commit comments