- Generated on Sun Mar 5 2023 00:28:22 for I2Cwrapper by
1.9.4
|
I2Cwrapper v0.5.0
Generic framework for Arduino I2C target devices
|
A helper class for the AccelStepperI2C and related libraries. More...
A helper class for the AccelStepperI2C and related libraries.
An object of type I2Cwrapper represents an I2C target and handles all communication with it. AccelStepperI2C, ServoI2C, and other modules use it for communicating with the target. To do so, an I2Cwrapper object is instantiated with the target's I2C address and then passed to its client object's (AccelStepperI2C etc.) constructor.
Public Member Functions | |
| I2Cwrapper (uint8_t i2c_address, uint8_t maxBuf=I2CmaxBuf) | |
| Constructor. More... | |
| bool | ping () |
| Test if target device is listening. More... | |
| void | reset (unsigned long resetDelay=defaultResetDelay) |
| Tells the target device to reset to its default state. It is recommended to reset the target every time the controller is started or restarted to put the target in a defined state. Otherwise it could happen that the target still manages units (steppers, etc.) which the controller 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 controller that something important happend. Currently used by AccelStepperI2C to inform about end stop hits and target reached events, and ESP32sensorsI2C to inform a touched button event. More... | |
| uint8_t | clearInterrupt () |
| Acknowledge to target that interrupt has been received, so that the target can clear the interupt condition and return the reason for the interrupt. More... | |
| unsigned long | setI2Cdelay (unsigned long delay) |
| Define a minimum duration of time that the controller keeps between I2C transmissions. This is to make sure that the target has finished its earlier task or has its answer to the controller's previous command ready (see Adjusting the I2C delay). 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... | |
| unsigned long | getI2Cdelay () |
| Returns currently set I2Cdelay. More... | |
| uint8_t | autoAdjustI2Cdelay (uint8_t maxLength=I2CmaxBuf - 3, uint8_t safetyMargin=2, uint8_t startWith=I2CdefaultDelay) |
| Set I2C delay to the smallest value that still allows error free transmissions. To determine this value, a simulation test is run: A number of dummy transmissions are repeatedly exchanged with the target using the pingBack() function, while successively decreasing the I2C delay. The test will stop as soon as a transmission error occurs. The smallest error free value (or 0 ms), increased by the safety margin, will be set as the new I2C delay. More... | |
| uint32_t | getVersion () |
| Get semver compliant version of target firmware. More... | |
| bool | checkVersion (uint32_t controllerVersion) |
| Get version of target 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 target. 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 target. 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 target. More... | |
| bool | resultOK = false |
| True if return value from previous function call was received successfully. More... | |
| I2Cwrapper::I2Cwrapper | ( | uint8_t | i2c_address, |
| uint8_t | maxBuf = I2CmaxBuf |
||
| ) |
Constructor.
| i2c_address | Address of the target device |
| maxBuf | [not implemented yet in the firmware, don't use] Upper limit of send and receive buffer including 1 crc8 byte and, for transmissions from the controller to the target, 2 header bytes. Note that this is corrently only implemented for the controller, but not in the firmware, so that it is not usable yet. |
| uint8_t I2Cwrapper::autoAdjustI2Cdelay | ( | uint8_t | maxLength = I2CmaxBuf - 3, |
| uint8_t | safetyMargin = 2, |
||
| uint8_t | startWith = I2CdefaultDelay |
||
| ) |
Set I2C delay to the smallest value that still allows error free transmissions. To determine this value, a simulation test is run: A number of dummy transmissions are repeatedly exchanged with the target using the pingBack() function, while successively decreasing the I2C delay. The test will stop as soon as a transmission error occurs. The smallest error free value (or 0 ms), increased by the safety margin, will be set as the new I2C delay.
| maxLength | Number of simulated test parameter bytes sent with each testing transmission, defaulting to the maximum bytes that are possible with the given I2C buffer size. This theoretical maximum (I2CmaxBuf minus three bytes for the message header) will not be fully used by most modules. So if you know what the maximum number of parameter bytes sent or receiced by any of the commands you will use in your project is, you can specify it here to get a more aggressive, shorter I2C delay. Leave it to the default to be on the safe side, in most cases it will not make a significant difference. |
| safetyMargin | A number of microseconds that will be added to the empirically determined minimum I2C delay. As the test transmissions do nothing but send back the amount of specified simulated parameter bytes, you will want to specify some extra time to allow for the time the controller will need to process any given command on top of the transmission itself. Its optimal value fully depends on how fast the target's module(s) do their job. It should usually be at least 1 ms. For the included modules 2 ms are a safe bet, that's why it's used as the default. |
| startWith | The delay value in ms to start with, defaults to I2CdefaultDelay (20 ms). Mainly meant to be used if serial debugging is enabled in the target firmware. If there is heavy debugging output, the default I2CdefaultDelay may sometimes be too low. |
| 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.
| bool I2Cwrapper::checkVersion | ( | uint32_t | controllerVersion | ) |
Get version of target firmware and compare it with library version.
| uint8_t I2Cwrapper::clearInterrupt | ( | ) |
Acknowledge to target that interrupt has been received, so that the target can clear the interupt condition and return the reason for the interrupt.
| unsigned long I2Cwrapper::getI2Cdelay | ( | ) |
Returns currently set I2Cdelay.
| uint32_t I2Cwrapper::getVersion | ( | ) |
Get semver compliant version of target firmware.
| bool I2Cwrapper::ping | ( | ) |
Test if target device is listening.
| void I2Cwrapper::prepareCommand | ( | uint8_t | cmd, |
| uint8_t | unit = -1 |
||
| ) |
| bool I2Cwrapper::readResult | ( | uint8_t | numBytes | ) |
| void I2Cwrapper::reset | ( | unsigned long | resetDelay = defaultResetDelay | ) |
Tells the target device to reset to its default state. It is recommended to reset the target every time the controller is started or restarted to put the target in a defined state. Otherwise it could happen that the target still manages units (steppers, etc.) which the controller does not know about.
| resetDelay | (new in v0.3.0, optional) delay in ms that the controller waits after sending the reset command to give the target enough time to reinitialize the firmware core and the activated modules. Defaults to defaultResetDelay (100 ms), 10 ms would probably be more than enough for all current modules. |
| 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 target.
| bool I2Cwrapper::sendCommand | ( | ) |
| 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 target.
| unsigned long I2Cwrapper::setI2Cdelay | ( | unsigned long | delay | ) |
Define a minimum duration of time that the controller keeps between I2C transmissions. This is to make sure that the target has finished its earlier task or has its answer to the controller's previous command ready (see Adjusting the I2C delay). 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.
| delay | Minimum time in between I2C transmissions in milliseconds. The default I2CdefaultDelay is a bit conservative at 20 ms to allow for serial debugging output to slow things down. 4 to 6 ms is usually more than enough. |
| 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 controller that something important happend. Currently used by AccelStepperI2C to inform about end stop hits and target reached events, and ESP32sensorsI2C to inform a touched button event.
| pin | Pin the target will use to send out interrupts. |
| activeHigh | If true, HIGH will signal an interrupt. |
| 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.
| SimpleBuffer I2Cwrapper::buf |
| bool I2Cwrapper::resultOK = false |
True if return value from previous function call was received successfully.
| bool I2Cwrapper::sentOK = false |
True if previous function call was successfully transferred to target.
1.9.4