A helper class for the AccelStepperI2C and related libraries. More...

Detailed Description

A helper class for the AccelStepperI2C and related libraries.

I split it from an earlier version of the AccelStepperI2C library when adding Servo support, to be able to have a clean separation librarywise between the two: The wrapper represents the I2C slave and handles all communication with it. AccelStepperI2C, ServoI2C, and others use it for communicating with the slave. To do so, an I2Cwrapper object is instantiated with the slave's I2C address and then passed to its client object's (AccelStepperI2C etc.) constructor.

Command codes

000 - 009 (reserved)
010 - 059 AccelStepperI2C
060 - 069 ServoI2C
070 - 079 PinI2C
080 - 239 (unused)
240 - 255 I2Cwrapper commands (reset slave, change address etc.)

: New classes could use I2Cwrapper to easily add even more capabilities to the slave, e.g. for driving DC motors, granted that the firmware is extended accordingly and the above list of uint8_t command codes is kept free from duplicates.

Public Member Functions
	I2Cwrapper (uint8_t i2c_address, uint8_t maxBuf=maxBufDefault)
	Constructor. More...

bool	ping ()
	Test if slave is listening. More...

void	reset ()
	Tells the slave to reset to it's default state. It is recommended to reset the slave every time the master is started or restarted to put it in a defined state. Else it could happen that the slave still manages units (steppers, etc.) which the master does not know about. More...

void	changeI2Caddress (uint8_t newAddress)
	Permanently change the I2C address of the device. The new address is stored in EEPROM (AVR) or flash memory (ESPs) and will be active after the next reset/reboot. More...

void	setInterruptPin (int8_t pin, bool activeHigh=true)
	Define a global interrupt pin which can be used by device units (steppers, servos...) to inform the master that something important happend. Currently used by AccelStepperI2C to inform about end stop hits and target reached events. More...

uint8_t	clearInterrupt ()
	Acknowledge a received interrupt to slave so that it can clear the interupt condition and return the reason for the interrupt. More...

unsigned long	setI2Cdelay (unsigned long delay)
	Define a minimum time that the master waits between I2C transmissions. This is to make sure that the slave has finished its earlier task or has its answer to the master's previous command ready. Particularly for ESP32 slaves this is critical, as due to its implementation of I2C slave mode, an ESP32 could theoretically send incomplete data if a request is sent too early. The actual delay will take the time spent since the last I2C transmission into account, so that it won't wait at all if the given time has already passed. More...

uint32_t	getSlaveVersion ()
	Get semver compliant version of slave firmware. More...

bool	checkVersion (uint32_t masterVersion)
	Get version of slave firmware and compare it with library version. More...

uint16_t	sentErrors ()
	Return and reset the number of failed commands sent since the last time this method was used. A command is sent each time a function call is transmitted to the slave. More...

uint16_t	resultErrors ()
	Return and reset the number of failed receive events since the last time this method was used. A receive event happens each time a function returns a value from the slave. More...

uint16_t	transmissionErrors ()
	Return and reset the sum of failed commands sent and failed receive events since the last time this method was used. Use this if you are only interested in the sum of all transmission errors, not in what direction the errors occurred. More...

void	prepareCommand (uint8_t cmd, uint8_t unit=-1)

bool	sendCommand ()

bool	readResult (uint8_t numBytes)

Public Attributes
SimpleBuffer	buf

bool	sentOK = false
	True if previous function call was successfully transferred to slave. More...

bool	resultOK = false
	True if return value from previous function call was received successfully. More...

Constructor & Destructor Documentation

◆ I2Cwrapper()

I2Cwrapper::I2Cwrapper	(	uint8_t	i2c_address,
		uint8_t	maxBuf = `maxBufDefault`
	)

Constructor.

Parameters

i2c_address	Address of the slave device
maxBuf	Upper limit of send and receive buffer including 1 crc8 byte

Member Function Documentation

◆ changeI2Caddress()

void I2Cwrapper::changeI2Caddress ( uint8_t newAddress )

Permanently change the I2C address of the device. The new address is stored in EEPROM (AVR) or flash memory (ESPs) and will be active after the next reset/reboot.

◆ checkVersion()

bool I2Cwrapper::checkVersion ( uint32_t masterVersion )

Get version of slave firmware and compare it with library version.

Returns: true if both versions match, i.a. are compatible.

◆ clearInterrupt()

uint8_t I2Cwrapper::clearInterrupt ( )

Acknowledge a received interrupt to slave so that it can clear the interupt condition and return the reason for the interrupt.

Returns: Reason for the interrupt as 8bit BCD with triggering unit in lower 4 bits and trigger reason in the upper 4 bits. 0xff in case of error.

See also: List of possible reasons an interrupt was triggered.

◆ getSlaveVersion()

uint32_t I2Cwrapper::getSlaveVersion ( )

Get semver compliant version of slave firmware.

Returns: major version in bits 0-7, minor version in bits 8-15; patch version in bits 16-23; 0xFFFFFFFF on error.

◆ ping()

bool I2Cwrapper::ping ( )

Test if slave is listening.

Returns: true if slave could be found under the given address.

◆ prepareCommand()

void I2Cwrapper::prepareCommand	(	uint8_t	cmd,
		uint8_t	unit = `-1`
	)

◆ readResult()

bool I2Cwrapper::readResult ( uint8_t numBytes )

◆ reset()

void I2Cwrapper::reset ( )

Tells the slave to reset to it's default state. It is recommended to reset the slave every time the master is started or restarted to put it in a defined state. Else it could happen that the slave still manages units (steppers, etc.) which the master does not know about.

◆ resultErrors()

uint16_t I2Cwrapper::resultErrors ( )

Return and reset the number of failed receive events since the last time this method was used. A receive event happens each time a function returns a value from the slave.

See also: sentErrors(), transmissionErrors()

◆ sendCommand()

bool I2Cwrapper::sendCommand ( )

◆ sentErrors()

uint16_t I2Cwrapper::sentErrors ( )

Return and reset the number of failed commands sent since the last time this method was used. A command is sent each time a function call is transmitted to the slave.

See also: resultErrors(), transmissionErrors()

◆ setI2Cdelay()

unsigned long I2Cwrapper::setI2Cdelay ( unsigned long delay )

Define a minimum time that the master waits between I2C transmissions. This is to make sure that the slave has finished its earlier task or has its answer to the master's previous command ready. Particularly for ESP32 slaves this is critical, as due to its implementation of I2C slave mode, an ESP32 could theoretically send incomplete data if a request is sent too early. The actual delay will take the time spent since the last I2C transmission into account, so that it won't wait at all if the given time has already passed.

Parameters

delay Minimum time in between I2C transmissions in milliseconds. The default I2CdefaultDelay is a bit conservative at 10 ms to allow for for serial debugging output to slow things down. You can try to go lower, if slave debugging is disabled.

Returns: Returns the previously set delay.

Todo:: ~~I2Cdelay is currently global; make it a per-slave setting.~~ implemented with I2Cwrapper.

◆ setInterruptPin()

void I2Cwrapper::setInterruptPin	(	int8_t	pin,
		bool	activeHigh = `true`
	)

Define a global interrupt pin which can be used by device units (steppers, servos...) to inform the master that something important happend. Currently used by AccelStepperI2C to inform about end stop hits and target reached events.

Parameters

pin	Pin the slave will use to send out interrupts.
activeHigh	If true, HIGH will signal an interrupt.

See also: AccelStepperI2C::enableInterrupts()

◆ transmissionErrors()

uint16_t I2Cwrapper::transmissionErrors ( )

Return and reset the sum of failed commands sent and failed receive events since the last time this method was used. Use this if you are only interested in the sum of all transmission errors, not in what direction the errors occurred.

Returns: Sum of sentErrors() and resultErrors()

See also: sentErrors(), resultErrors()

Member Data Documentation

◆ buf

SimpleBuffer I2Cwrapper::buf

◆ resultOK

bool I2Cwrapper::resultOK = false

True if return value from previous function call was received successfully.

◆ sentOK

bool I2Cwrapper::sentOK = false

True if previous function call was successfully transferred to slave.

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

Detailed Description

Public Member Functions

Public Attributes

Constructor & Destructor Documentation

◆ I2Cwrapper()

Member Function Documentation

◆ changeI2Caddress()

◆ checkVersion()

◆ clearInterrupt()

◆ getSlaveVersion()

◆ ping()

◆ prepareCommand()

◆ readResult()

◆ reset()

◆ resultErrors()

◆ sendCommand()

◆ sentErrors()

◆ setI2Cdelay()

◆ setInterruptPin()

◆ transmissionErrors()

Member Data Documentation

◆ buf

◆ resultOK

◆ sentOK