|
|
pin_t | trigPin = PIN_INVALID |
| | TRIG pin (OUTPUT)
|
| |
|
pin_t | echoPin = PIN_INVALID |
| | ECHO pin (input)
|
| |
|
pin_t | unusedPin1 = PIN_INVALID |
| | SCK output (1 mHz)
|
| |
|
pin_t | unusedPin2 = PIN_INVALID |
| | LRCK output (32 kHz)
|
| |
|
float | maxLengthM = 1.0 |
| | Maximum distance that can be read (affects memory and sample period)
|
| |
|
std::function< void(DistanceResult)> | callback = nullptr |
| | Callback after sample or error.
|
| |
|
size_t | numSamples = 0 |
| | Number of samples, depends on maxLengthM and leadingOverhead.
|
| |
|
uint16_t * | rxBuffer = nullptr |
| | ECHO pin buffer.
|
| |
|
uint16_t * | txBuffer = nullptr |
| | TRIG pin buffer.
|
| |
|
bool | isIdle = true |
| | True if in idleState.
|
| |
|
DistanceResult | lastResult |
| | The last sample read (single, periodic, or alarm)
|
| |
|
unsigned long | samplePeriodic = 0 |
| | If in periodic sample mode, the number of milliseconds in period (0 = disabled)
|
| |
|
DistanceAlarm | distanceAlarm |
| | Distance alarm mode settings, if enabled. If distance == 0, then disabled.
|
| |
|
bool | inAlarm = false |
| | True if the distance alarm has been notified.
|
| |
|
size_t | leadingOverhead = 152 |
| | How long in 16-bit samples from falling TRIG to rising ECHO (maximum, typical). Must be a multiple of 4.
|
| |
|
unsigned long | safetyTimeoutMs = 300 |
| | Maximum amount of time to wait if sensor does not respond.
|
| |
|
unsigned long | sampleTime = 0 |
| | millis value when last sample was taken, used for periodic sampling
|
| |
|
std::function< void(JSN_SR04_Gen3 &)> | stateHandler = &JSN_SR04_Gen3::idleState |
| | state handler function
|
| |
Class for a JSN-SR04 ultrasonic distance sensor.
Note: You can effectively only have one instance of this class per device, because there is only one I2S peripheral, which is what is used to implement the device driver.
| unsigned long JSN_SR04_Gen3::getSampleTimeMs |
( |
| ) |
const |
Returns the number of milliseconds it takes to process a sample.
- Returns
- unsigned long number of milliseconds
In practice it might take a few milliseconds longer because of the delays in dispatching loop(). The value is calculated from the maxLengthM and leadingOverhead values.
With the default value of 1 meter maximum and 152 leadingOverhead, this returns 9 milliseconds.
In theory you could sample at around every 9 milliseconds, maybe 10, but it's probably best to limit it to 100 milliseconds, or even 500 milliseconds, to be safe. If you sample frequently, be sure to handle the case where BUSY status is returned. This means that that sensor has not yet reset the ECHO output low and a sample cannot be taken yet.
Note that the callback will not be called for at least this long, regardless of distance! The reason is that the sample buffer is not processed until the DMA engine stops writing to the entire buffer, and then it waits until in loop context again.
Specify a callback function to be called on samples, errors, and alarm conditions.
- Parameters
-
| callback | The callback function |
- Returns
- JSN_SR04_Gen3& This object, for chaining options, fluent-style
The callback function has the prototype;
void callback(DistanceResult distanceResult)
It can be a C++11 lambda, if desired, to call a class member function.
| JSN_SR04_Gen3 & JSN_SR04_Gen3::withMaxLengthMeters |
( |
float |
maxLengthM | ) |
|
|
inline |
The maximum length that can be measured in meters. Default: 1 meter.
- Parameters
-
- Returns
- JSN_SR04_Gen3& This object, for chaining options, fluent-style
This affects the amount of memory that is used, and also the amount of time a sampling takes. See the README for more information.
At the default is 1 meter, the memory is 2,080 bytes and the time is 9 milliseconds.
| JSN_SR04_Gen3 & JSN_SR04_Gen3::withSamplePeriodic |
( |
std::chrono::milliseconds |
period | ) |
|
|
inline |
Enabling periodic sampling mode.
- Parameters
-
| period | The sampling period as a chrono literal, such as 500ms, 10s, etc. |
- Returns
- JSN_SR04_Gen3& This object, for chaining options, fluent-style
It's recommended to specify a sampling period greater than safetyTimeoutMs milliseconds (currently 300). However, in practice you can specify a much faster sampling period, as low as getSampleTimeMs() milliseconds. The latter varies depending on the max length meters. At the default value of 1 meter, you can use a periodic sample rate at low as 10 milliseconds, however you might not get every sample. The sensor may not always reset in time an the BUSY error will be called on the callback.
| JSN_SR04_Gen3 & JSN_SR04_Gen3::withSamplePeriodicMs |
( |
unsigned long |
periodMs | ) |
|
|
inline |
Enabling periodic sampling mode.
- Parameters
-
| periodMs | The sampling period in milliseconds |
- Returns
- JSN_SR04_Gen3& This object, for chaining options, fluent-style
It's recommended to specify a sampling period greater than safetyTimeoutMs milliseconds (currently 300). However, in practice you can specify a much faster sampling period, as low as getSampleTimeMs() milliseconds. The latter varies depending on the max length meters. At the default value of 1 meter, you can use a periodic sample rate at low as 10 milliseconds, however you might not get every sample. The sensor may not always reset in time an the BUSY error will be called on the callback.
| JSN_SR04_Gen3 & JSN_SR04_Gen3::withUnusedPins |
( |
pin_t |
unusedPin1, |
|
|
pin_t |
unusedPin2 |
|
) |
| |
|
inline |
You must specify two GPIO that are not otherwise used that will be used as outputs by this library.
- Parameters
-
| unusedPin1 | A pin, such as D2 or A0, or another port that is not being used, such as TX, RX, DAC, etc. |
| unusedPin2 | A pin, such as D2 or A0, or another port that is not being used, such as TX, RX, DAC, etc. Must be different than unusedPin1. |
- Returns
- JSN_SR04_Gen3& This object, for chaining options, fluent-style
You need to dedicate two other pins, unusedPin1 and unusedPin2. These must not be the same pin, and can't be used for anything else for all practical purposes. This is due to how the I2S peripheral works. You have to assign the I2S LRCK and SCK to pins or the nRF52 I2S peripheral won't initialize. You won't need these outputs for anything, but they do need to be assigned GPIOs. The signals happen to be 32 kHz for the LRCK and 1 MHz for SCK while getting a distance sample.
