Here you can find the library description of the I2C NavKey for the Arduino IDE. For more details of the functionality of the board, please read the Datasheet
The I2C NavKey is available on Tindie!
The library makes available the class i2cNavKey To initialize the library, you have to declare an instance of the class i2cNavKey for each encoders. For example:
i2cNavKey navkey(0x10);Declaration of one encoder with the address 0x10. All the jumpers are open.
i2cNavKey navkey(0b0010000);Declaration of the same I2CNavKey but in binary format.
i2cNavKey navkey1(0x11); //A0 shorted
i2cNavKey navkey2(0x12); //A1 shortedDeclaration of two I2CNavKey with the address 0x11 and 0x12 in two separated variable.
i2cNavKey encoder[2] = { i2cNavKey(0x11), i2cNavKey(0x12)};Declaration of an array of the two I2CNavKey with the address 0x11 and 0x12.
This library support the callback functionality. There is the possibility to link a function to a specific interrupt of the I2CNavKey, in this way the function is automatically called when the I2CNavKey generates an interrupts.
A callback function must be declared as the following:
void NAME_OF_THE_FUNCTION(i2cNavKey* obj)The argument i2cNavKey obj* is the pointer to the class that called the method.
There are 26 possible events:
| Event | Description |
|---|---|
| onArrowsPush | One of the 4 direction keys is pressed |
| onArrowsRelese | One of the 4 direction keys is released |
| onUpPush | Arrow up is pressed |
| onUpRelease | Arrow up is released |
| onDownPush | Arrow down is pressed |
| onDownRelease | Arrow down is released |
| onRightPush | Arrow right is pressed |
| onRightRelease | Arrow right is released |
| onLeftPush | Arrow left is pressed |
| onLeftRelease | Arrow left is released |
| onCentralPush | central button is pressed |
| onCentralRelease | central button is released |
| onCentralDoublePush | central button is double pushed |
| onIncrement | The counter value is incremented |
| onDecrement | The counter value is decremented |
| onChange | The counter value is incremented or decremented |
| onMax | The counter value reach the maximum threshold |
| onMin | The counter value reach the minimum threshold |
| onMinMax | The counter value reach the maximum or minimum threshold |
| onGP1Rise | GP1 configured as input, rising edge |
| onGP1Fall | GP1 configured as input, falling edge |
| onGP2Rise | GP2 configured as input, rising edge |
| onGP2Fall | GP2 configured as input, falling edge |
| onGP3Rise | GP3 configured as input, rising edge |
| onGP3Fall | GP3 configured as input, falling edge |
| onFadeProcess | Fade process terminated |
i2cNavKey navkey(0x10);// Class declaration
...
// Simple callback that ist's called when the encoder is rotated
void navkey_encoder_change(i2cNavKey* obj) {
Serial.println( obj->readCounterByte()); //Print on the terminal the counter value.
}
...
navkey.onChange = navkey_encoder_change; //Attach the event to the callback function.
}
If you need to remove the link with a callback, you just need to define:
navkey.onChange=NULL;This is used for initializing the I2CNavKey by writing the configuration register. The parameters can be concatenated in OR mode. The possible parameters are the following:
| Parameter | Description |
|---|---|
| INT_DATA | The Threshold, counter step and counter value are used with integer numbers |
| FLOAT_DATA | The Threshold, counter step and counter value are used with floating numbers |
| WRAP_ENABLE | Wrap enable. When the counter value reaches the CMAX+1, restart to the CMIN and vice versa |
| WRAP_DISABLE | Wrap disable. When the counter value reaches the CMAX or CMIN, the counter stops to increasing or decreasing |
| DIRE_LEFT | Rotate left side to increase the value counter |
| DIRE_RIGHT | Rotate right side to increase the value counter |
| IPUP_DISABLE | Disable the internal pull-up on the INT pin |
| IPUP_ENABLE | Enable the internal pull-up on the INT pin |
| CLK_STRECH_ENABLE | Enable the I2C clock stretch |
| CLK_STRECH_DISABLE | Disable the I2C clock stretch |
| EEPROM_BANK1 | Select the first EEPROM bank |
| EEPROM_BANK2 | Select the second EEPROM bank |
| RESET | Reset the board |
navkey.begin(i2cNavKey::INT_DATA | i2cNavKey::WRAP_ENABLE | i2cNavKey::DIRE_RIGHT | i2cNavKey::IPUP_ENABLE);Reset of the board. In this command there is 8ms delay in order to make the board correctly restart.
This 3 functions are used to configure the GP pins. The parameters are the same for all of the 3 GP pins. The interrupt configurations are used only when the pin is configured as digital input.
| Parameter | Description |
|---|---|
| GP_PWM | Set the GP pin as PWM output |
| GP_OUT | Set the GP pin as digital output |
| GP_AN | Set the GP pin as analog input |
| GP_IN | Set the GP pin as digital input output |
| GP_PULL_EN | Enable the internal pull-up of the pin |
| GP_PULL_DI | Disable the internal pull-up of the pin |
| GP_INT_DI | Disable the pin interrupt |
| GP_INT_PE | Enable the interrupt at the positive edge |
| GP_INT_NE | Enable the interrupt at the negative edge |
| GP_INT_BE | Enable the interrupt at the positive and negative edge |
navkey.writeGP1conf(i2cNavKey::GP_IN | i2cNavKey::GP_PULL_EN | i2cNavKey::GP_INT_BE ); //Configure the GP1 as digital input with the pull-up enable and the interrupt enabled on both edges
navkey.writeGP2conf(i2cNavKey::GP_PWM); //Configure the GP2 as PWM output
This method is used for enabling or disabling the interrupt source selectively. When an interrupt event occurs, the INT pin goes low and the event is stored in the status register.
| Parameter | Description |
|---|---|
| UPR | Arrow up is released |
| UPP | Arrow up is pressed |
| DNR | Arrow down is released |
| DNP | Arrow down is pressed |
| RTR | Arrow right is released |
| RTP | Arrow right is pressed |
| LTR | Arrow left is released |
| LTP | Arrow left is pressed |
| CTRR | Central button is released |
| CTRP | Central button is pressed |
| CTRDP | Central button is double pushed |
| RINC | Encoder is rotated in the increment direction |
| RDEC | Encoder is rotated in the decrement direction |
| RMAX | Maximum threshold is reached |
| RMIN | Minimum threshold is reached |
| INT_2 | An event on the interrupt 2 register occurs |
This method auto configures the INTCONF register according to the attached callback. For the proper use, must be called after the definition of the last event property.
navkey.onUpPush = navkey_Up;
navkey.onDownPush = navkey_Down;
navkey.onLeftPush = navkey_Left;
navkey.onRightPush = navkey_Right;
navkey.onIncrement = navkey_increment;
navkey.onDecrement = navkey_decrement;
navkey.onMax = navkey_max;
navkey.onMin = navkey_min;
navkey.onButtonPush = navkey_push;
navkey.onButtonDoublePush = navkey_double_push;
/* Enable the I2C Encoder V2 interrupts according to the previus attached callback */
navkey.autoconfigInterrupt();
This method is used for setting the window period DPPERIOD of the double push of the central button. When the value is 0, the double push option is disabled. The I2C NavKey will multiplies this value by 10 (value x10).
navkey.writeDoublePushPeriod(50); //Set a period for the double push of 500ms This method is used for setting the fade speed FADEGP of the RGB LED of the rotary encoder. It the value is 0, the fade option is disabled.
navkey.writeFadeGP(5); //GP Fade enabled with 5ms step This method is used to set a gamma correction in case the GP pin is set to PWM
| Parameter | Description |
|---|---|
| GAMMA_1 | Gamma is 1, in thi case the PWM is lenear |
| GAMMA_1_8 | Gamma is 1.8 |
| GAMMA_2 | Gamma is 2 |
| GAMMA_2_2 | Gamma is 2.2 |
| GAMMA_2_4 | Gamma is 2.4 |
| GAMMA_2_6 | Gamma is 2.6 |
| GAMMA_2_8 | Gamma is 2.8 |
navkey.writeGammaGP1(i2cNavKey::GAMMA_1);
navkey.writeGammaGP2(i2cNavKey::GAMMA_2);
navkey.writeGammaGP3(i2cNavKey::GAMMA_2_2);Read the I2CNavKey status register ISTATUS. In case of events the attached callback is called. Return value is true in case of some event, otherwise is false In case an event of the I2STATUS register, the I2STATUS is automatically be read.
if ( navkey.updateStatus() == true) {
// Something happens
}Must be called after updateStatus(), this method is used for checking if some event occurs on the ISTATUS register. Return value is true in case of the event occurred, otherwise is false Possible parameters are:
| Parameter | Description |
|---|---|
| UPR | Arrow up is released |
| UPP | Arrow up is pressed |
| DNR | Arrow down is released |
| DNP | Arrow down is pressed |
| RTR | Arrow right is released |
| RTP | Arrow right is pressed |
| LTR | Arrow left is released |
| LTP | Arrow left is pressed |
| CTRR | Central button is released |
| CTRP | Central button is pressed |
| CTRDP | Central button is double pushed |
| RINC | Encoder is rotated in the increment direction |
| RDEC | Encoder is rotated in the decrement direction |
| RMAX | Maximum threshold is reached |
| RMIN | Minimum threshold is reached |
| INT_2 | An event on the interrupt 2 register occurs |
if ( navkey.updateStatus() == true) {
if ( navkey.readStatus(RINC)) {
Serial.print("Increment ");
}
if ( navkey.readStatus(RDEC)) {
Serial.print("Decrement ");
}
if ( navkey.readStatus(RMAX)) {
Serial.print("Maximum threshold: ");
}
if ( navkey.readStatus(RMIN)) {
Serial.print("Minimum threshold: ");
}
if ( navkey.readStatus(PUSHR)) {
Serial.println("Push button Released");
}
if ( navkey.readStatus(PUSHP)) {
}
if ( navkey.readStatus(PUSHD)) {
Serial.println("Double push!");
}Return the status of the register ESTATUS
Must be called after updateStatus(), this method is used for checking if some event occurred on the secondary interrupt status I2STATUS register. Return value is true in case of the event occurred, otherwise is false Possible parameters are:
| Parameter | Description |
|---|---|
| GP1_POS | Positive edge on the GP1 pin |
| GP1_NEG | Negative edge on the GP1 pin |
| GP2_POS | Positive edge on the GP2 pin |
| GP2_NEG | Negative edge on the GP2 pin |
| GP3_POS | Positive edge on the GP3 pin |
| GP3_NEG | Negative edge on the GP3 pin |
| FADE_INT | Fade process finished |
if ( navkey.updateStatus() == true) {
if ( navkey.readInt2(GP1_POS)) {
Serial.print("GP1 positive edge");
}
if ( navkey.readInt2(GP1_NEG)) {
Serial.print("GP1 negative edge ");
}
if ( navkey.readInt2(GP2_POS)) {
Serial.print("GP2 positive edge");
}
if ( navkey.readInt2(GP2_NEG)) {
Serial.print("GP2 negative edge ");
}
if ( navkey.readInt2(GP3_POS)) {
Serial.print("GP3 positive edge");
}
if ( navkey.readInt2(GP3_NEG)) {
Serial.print("GP3 negative edge ");
}
if ( navkey.readInt2(FADE_INT)) {
Serial.println("Fade process finished");
}Return the status of the register I2STATUS
When this function is called, it performs a I2C reading. This function return true when the fade running, otherwise return false
| Parameter | Description |
|---|---|
| FADE_GP1 | Fade process status of the GP1 |
| FADE_GP2 | Fade process status of the GP2 |
| FADE_GP3 | Fade process status of the GP3 |
Return the value of the register FSTATUS.
Return the counter value in the format int32_t, by reading all the 4 bytes of the counter value registers.
Return the counter value in the format int16_t, by reading the 2 LSB of the counter value registers. Useful when the counter register is between the values -32768 to 32767.
Return the counter value in the format int8_t, by reading the LSB byte of the counter value register. Useful when the counter register is between the values -128 to 127
Return the counter value in the format float, by reading all the 4 bytes of the counter value registers. For using this function you have to configure the board with the parameter FLOAT_DATA.
Return the maximum threshold in format int32_t, bye reading all the 4 bytes of the counter Max.
Return the maximum threshold in format float, bye reading all the 4 bytes of the counter Max.
Return the minimum threshold in format int32_t, by reading all the 4 byte of the counter Min.
Return the minimum threshold in format float, bye reading all the 4 bytes of the counter Min.
Return the minimum threshold in format int32_t, by reading all the 4 bytes of the ISTEP registers.
Return the step value in format float, by reading all the 4 bytes of the ISTEP registers .
Return the value of the RLED register.
Return the value of the GLED register.
Return the value of the BLED register.
Return the value of the GP1REG register. If the GP1 is configured as input, it's possible to read the logic status of the pin: 1 when the pin is high, otherwise 0. If the GP1 is configured as analog, it's possible to read the 8bit of the ADC.
Return the value of the GP2REG register. If the GP2 is configured as input, it's possible to read the logic status of the pin: 1 when the pin is high, otherwise 0. If the GP2 is configured as analog, it's possible to read the 8bit of the ADC.
Return the value of the GP3REG register. If the GP3 is configured as input, it's possible to read the logic status of the pin: 1 when the pin is high, otherwise 0. If the GP3 is configured as analog, it's possible to read the 8bit of the ADC.
Return the value of the ANTBOUNC register.
Return the value of the DPPERIOD register.
Return the value of the FADEGP register.
Return the value of the EEPROM register. This function automatically manage the setting of the first and second memory bank.
Read a generic register of the I2C Encoder V2. The input parameter is the address of the register.
Read a generic register of the I2C Encoder V2, in 16bit format. The input parameter is starting address of the registers.
Read a generic register of the I2C Encoder V2, in 32bit format. The input parameter is starting address of the registers.
Return the ID code of the I2C NavKey, it's a fixed number 0x5B
Return the version of the I2C NavKey.
Write the counter value register with a int32_t number. All of the 4 bytes are wrote.
Write the counter value register with a float number. All of the 4 bytes are wrote.
Write the Max register with a int32_t number. All of the 4 bytes are wrote.
Write the Max register with a float number. All of the 4 bytes are wrote.
Write the Min register with a int32_t number. All of the 4 bytes are wrote.
Write the Min register with a float number. All of the 4 bytes are wrote.
Write the increment step with a int32_t number. All of the 4 bytes are wrote.
Write the increment step with a float number. All of the 4 bytes are wrote.
Write the GP1REG register. If the GP1 is configure as PWM with this method it's possible to write the PWM value. If the GP1 is configure as output with this method it's possible to write the logic status: 1 for high, while 0 for low.
Write the GP2REG register. If the GP2 is configure as PWM with this method it's possible to write the PWM value. If the GP2 is configure as output with this method it's possible to write the logic status: 1 for high, while 0 for low.
Write the GP3REG register. If the GP3 is configure as PWM with this method it's possible to write the PWM value. If the GP3 is configure as output with this method it's possible to write the logic status: 1 for high, while 0 for low.
Write the DPPERIOD register.
Write the FADEGP register.
Write the EEPROM memory. The input parameter add is the address. This method automatically change the first or the second bank. The input parameter data is the data taht will be written.