RCWL_1X05 Class Reference

Public Types
enum	RCWL_1X05_mode : uint8_t { oneShot , triggered , continuous }

Public Member Functions
	RCWL_1X05 ()
	Constructor. More...
bool	begin (TwoWire *myWire, uint8_t i2c_addr=RCWL_1X05_ADDR)
	Call begin() first. Optionally, pass a I2C class other than Wire to be used for communicating with the sensor. More...
bool	begin ()
	Use begin() without parameters to use the standard Wire.h library and the standard address 0x57 for communicating with the sensor. Your code must call Wire.begin() before calling this. More...
void	setMode (RCWL_1X05_mode newMode)
	Choose mode of operation, default is oneShot. Will determine what will happen when you call read(). More...
void	setTemperature (int16_t newTemperature)
	As the speed of sound varies with air temperature, all measurements will be adjusted according to temperature The default is 20° Celsius. Use this method to change the default. More...
void	setTimeout (unsigned long newTimeout)
	I2C targets cannot inform the controller if a measurement has completed. So we'll need a timeout, after which the controller can safely assume that a measurement will have completed. Depending on mode, this timeout determines. More...
uint32_t	read ()
	Get one measurement. Operation and usage depends on current mode, see setMode() for details. Results can be raw or filtered with setFilter(), default is raw. More...
bool	trigger ()
	Initiate a measurement in triggered mode. Don't use in other modes. More...
bool	update ()
	Update measurement and initiate subsequent measurement if completed in continuous mode. Don't use in other modes. Call as frequently as possible, if you want your measured values to be current. If you omit calling this, you'll get only garbage from read() in continuous mode. More...
void	setFilter (bool on)
	read() reports raw measurements by default. The filter buffers the last five measurements and reports the median value of these five. Out-of-range values smaller than minDistace and larger than maxDistance are ignored, i.e. not entered into the buffer. Note that depending on your frequency of measurements, the filter comes at the cost of increased lagginess. Probably it makes most sense to use the filter in continuous mode. More...

Member Enumeration Documentation

RCWL_1X05_mode

enum RCWL_1X05::RCWL_1X05_mode : uint8_t

Mode of operation, used by RCWL_1X05::setMode()

Enumerator
oneShot	blocking one time measurement
triggered	non blocking, manually initiated measurement
continuous	non blocking, automatic measurement, needs update()

Constructor & Destructor Documentation

RCWL_1X05()

RCWL_1X05::RCWL_1X05

(

)

Constructor.

Member Function Documentation

begin() [1/2]

bool RCWL_1X05::begin

(

)

Use begin() without parameters to use the standard Wire.h library and the standard address 0x57 for communicating with the sensor. Your code must call Wire.begin() before calling this.

Returns

true if communication with the sensor was successfully established.

begin() [2/2]

bool RCWL_1X05::begin	(	TwoWire *	myWire,
		uint8_t	i2c_addr = RCWL_1X05_ADDR
	)

Call begin() first. Optionally, pass a I2C class other than Wire to be used for communicating with the sensor.

Parameters

myWire	Object of type TwoWire. Needs to be initialized and ready for transmission. We do not call TowWire.begin() in this code so that you can set your own pins etc. if needed.
i2c_addr	Probably useless, as the sensor currently only supports the fixed address 0x57.

Returns

true if communication with the sensor was successfully established.

read()

uint32_t RCWL_1X05::read

(

)

Get one measurement. Operation and usage depends on current mode, see setMode() for details. Results can be raw or filtered with setFilter(), default is raw.

Get measurement. Operation and usage depends on current mode, setMode() for details.

Returns

distance in millimeters. 0 if no data was available (yet), i.e. a trigger() call was missing in triggered mode, or the timeout set with setTimeout() was too short. Note that the minimal distance/blind zone of the sensor is 250(!) mm, so any value less or equal 250 mm cannot be trusted.

See also

setFilter()

Returns

distance in millimeters, 0 on timeout. Note that minimal distance/blind zone of the sensor is 250mm(!), so any value less or equal 250mm cannot be trusted.

setFilter()

void RCWL_1X05::setFilter

(

bool

on

)

read() reports raw measurements by default. The filter buffers the last five measurements and reports the median value of these five. Out-of-range values smaller than minDistace and larger than maxDistance are ignored, i.e. not entered into the buffer. Note that depending on your frequency of measurements, the filter comes at the cost of increased lagginess. Probably it makes most sense to use the filter in continuous mode.

Parameters

on	true to turn filter on.

Note

Filter code was adapted from the fine AsyncSonar libarary by Luis Llamas.

setMode()

void RCWL_1X05::setMode

(

RCWL_1X05_mode

newMode

)

Choose mode of operation, default is oneShot. Will determine what will happen when you call read().

Parameters

newMode

One of (see RCWL_1X05_mode)

• RCWL_1X05::oneShot: read() will initiate a measurement, wait for its completion and return the measured value. Note that read() is blocking in this mode.
• RCWL_1X05::triggered: You'll need to manually initiate a measurement with trigger(), after that your sketch is free to do something else. You can read() the value after measurement has been completed, but it is your responsibility to wait long enough before reading (see setTimeout()).
• RCWL_1X05::continuous: Measurements will be triggered automatically after the previous measurement has completed. However, this happens not automatically (no interrupt magic, here), instead your code needs to call update() as often as possible in this mode. read() will return the most recent completed measurement, so results may be stale (see setTimeout()).

setTemperature()

void RCWL_1X05::setTemperature

(

int16_t

newTemperature

)

As the speed of sound varies with air temperature, all measurements will be adjusted according to temperature The default is 20° Celsius. Use this method to change the default.

Parameters

newTemperature

in Celsius

setTimeout()

void RCWL_1X05::setTimeout

(

unsigned long

newTimeout

)

I2C targets cannot inform the controller if a measurement has completed. So we'll need a timeout, after which the controller can safely assume that a measurement will have completed. Depending on mode, this timeout determines.

1. the duration after which read() will return in oneShot mode,
2. the minimum time the controller should do other things after calling trigger() and before calling read() in triggered mode, and
3. the maximum staleness of a value in continuous mode.

The default is 100 ms, the recommended minimum value given in the "datasheet". I found that I could safely reduce this to about 30-40 ms without problems for ranges up to ca. 3 m, so play around with this if timing is critical. You know that your timeout is too short if you read 0 values in raw (non filtered) mode.

Note that you cannot simply calculate your timeout from the maximum range you need to able to detect in your application, as there is some unknown overhead involved, so trial and error is probably the best approach if you want to minimize timeout.

Parameters

newTimeout

in milliseconds

trigger()

bool RCWL_1X05::trigger

(

)

Initiate a measurement in triggered mode. Don't use in other modes.

Returns

true if trigger command was successfully transmitted

See also

setMode()

update()

bool RCWL_1X05::update

(

)

Update measurement and initiate subsequent measurement if completed in continuous mode. Don't use in other modes. Call as frequently as possible, if you want your measured values to be current. If you omit calling this, you'll get only garbage from read() in continuous mode.

Returns

true if a measurement was completed since last calling update().

---

The documentation for this class was generated from the following files:

• RCWL_1X05.h
• RCWL_1X05.cpp