XNORIT-WAN

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== XnorBus I2C Communication Library: ======

===== I2C Slave devices library =====
==== Instantiate 'XnorBusSlave'object ====
  - Include the library globally.
  - Instantiate byte array variable. This is used as a shared memory on the I2C bus. Size of array is free to choose.  
  - Instantiate XnorBusSlave object, passing an I2C ID byte followed by the previously instantiated byte array. 

<code c>
#include "XnorBusSlave.h"
byte bus_memory[4]; 
XnorBusSlave xbus(8, bus_memory); // Create slave object with ID 8, set shared bus memory byte array. 
</code>

//Example code above creates an bus_memory byte array that is 4 bytes long. Next the slave is given ID number 8, and the bus_memory array is passed to the XnorBusSlave object. All data stored inside this array is (read/write) accessible for the I2C connected master. 

//
==== Bugs: ====
<WRAP center round important 80%>
**Static void bug!** 
Line 31 and 47 should not be declared as static!
This causes no issue on attinycore, but returns an error in the minicore stack. 
</WRAP>


==== Downloads ====
  * Download full slaves library code + example: {{ :xnorit:public:dependencies:xnorbus:arduinoi2cslavetest.rar |}} <color #ed1c24>**Static void bug hasn't been fixed.**</color> 
  * {{ :xnorit:public:dependencies:xnorbus:xnorbusslave.h | XnorBusSlave.h}}  <color #22b14c>**Static void bug has been fixed.**</color> 
  * {{ :xnorit:public:dependencies:xnorbus:xnorbusslave1.h | XnorBusSlave1.h}}  <color #22b14c>**Static void bug has been fixed.**</color>
  * {{ :xnorit:public:dependencies:xnorbus:xnorduino_v2.zip |}} <color #22b14c>**Static void bug has been fixed. Added ECC checksum to communication protocol. Only compatible with XnorbusMaster v2! **</color>

\\

===== I2C Master device(s) library usage: =====

==== Instantiate 'XnorBusMaster'object ====
  - Include the library globally.
  - Instantiate XnorBusMaster object, passing an I2C ID byte.

<code c>
#include "XnorBusMaster.h"
XnorBusMaster xbus(8); // Init slave device object with ID 8, named xbus. 
</code>

<WRAP center round tip 90%>
Configure multiple slaves as multiple XnorBusMaster objects for ease of use!
</WRAP>

\\ 
==== Set bus request configuration: ====
Before reading/writing data from/to a slave bus device, some configuration has to be configured.
\\ This can be done using the following code:
<code c>
xbus.SetBusRequest(0, 4); // Read slave device byte memory array starting from index 0, read 4 bytes. 
</code>

In the above example, the master is configured to read the shared slaves memory byte array starting from index 0, and read a total of 4 bytes. In this example (based on the previous explained slave) this would be the whole array. 

  * If for performance reasons the user want's to lower the amount of data transfer over the I2C bus, it is possible to change the configuration to read less bytes. 
  * If for expansion reasons the user want's to increase the amount of bytes transferred, you can change the configuration to read more bytes. 

<WRAP center round important 90%>
Note that the slaves shared bus memory has to be configured with the correct size before the master can request data of this shared memory.  
</WRAP>


 
=== Examples: ===
<code c>
xbus.SetBusRequest(0, 2); // Read slave device byte memory array starting from index 0, read 2 bytes.
xbus.SetBusRequest(0, 1); // Read slave device byte memory array starting from index 0, read 1 byte.
xbus.SetBusRequest(3, 1); // Read slave device byte memory array starting from index 3, read 1 byte. 
xbus.SetBusRequest(2, 2); // Read slave device byte memory array starting from index 2, read 2 bytes.
xbus.SetBusRequest(1, 3); // Read slave device byte memory array starting from index 1, read 3 bytes.
</code>

<WRAP center round info 90%>
The SetBusRequest function does not transmit data over the I2C bus. Changes are kept locally in the masters memory and only transmitted to the slave when required. (on Read or Write).
</WRAP>

==== Write bytes to slave: ====
After using the 'SetBusRequest' function data can be written to the slave device.
  - First, create a byte array that contains the data to write. \\This byte array has to be of the same size that was configured using the 'SetBusRequest' function.
  - Second, use the 'Write' function to write the preconfigured byte (as shown in the example underneath).

<code c> 
  byte b[] = {100,101,102,103}; // Init byte array containing data to write. 
  xbus.Write(b); // Write to slave:
</code>

Combined with the 'SetBusRequest' function this would look like: 
<code c>
  xbus.SetBusRequest(0, 4); // Configure bus request to read/write data from byte array index 0, length of 4 bytes. 
  byte b[] = {100,101,102,103}; // Init byte array containing data to write. 
  xbus.Write(b); // Write to slave:
</code>

=== Examples: ===

<code c>
  // If a user only needs to write 1 byte to the third index of the slave this can be done as followed: 
  xbus.SetBusRequest(2, 1); // Configure bus request to read/write data from byte array index 2, length of 1 
  byte b[] = {102}; // Init byte array containing data to write. 
  xbus.Write(b); // Write to slave:

  // If a user needs to write 2 bytes, starting on the second index:
  xbus.SetBusRequest(1, 2); // Configure bus request to read/write data from byte array index 1, length of 2 bytes. 
  byte b[] = {101,102}; // Init byte array containing data to write. 
  xbus.Write(b); // Write to slave:

  // If data is written in a loop, the 'SetBusRequest' function is not required inside the loop:
  xbus.SetBusRequest(1, 2);
  while(true)
  {
    byte b[] = {101,102}; // Init byte array containing data to write.   
    xbus.Write(b); // read slave, passing byte array to store requested data.
    delay(10);
  }
</code>

<WRAP center round info 90%>
The Write function will always write the 'SetBusRequest' configuration to the slave in the first 3 bytes of data transfer. This is part of the library's protocol. 
</WRAP>

==== Read bytes from slave: ====
To read bytes from a slave, first the 'SetBusRequest' protocol function has to be used at least once to configure the data to request. Data can be requested using the 'Read' function with a passed byte array as argument. The read data is written to the passed byte array. 

<code c> 
  byte q[2]; // init byte array of size 2
  xbus.Read(q); // read slave, passing byte array to store requested data. 
</code>

Combined with the 'SetBusRequest' function this would look as followed: 
<code c>
  xbus.SetBusRequest(1, 2); // request data from slaves memory starting at index 1, request 2 bytes.    
  byte q[2]; // init byte array of size 2
  xbus.Read(q); // read slave, passing byte array to store requested data. 
</code>

=== Examples: ===
<code c>
  // If data from a slave is requested in a loop, the 'SetBusRequest' function is not required inside the loop:
  xbus.SetBusRequest(0, 4);
  byte q[4]; // init byte array of size 2
  while(true)
  {  
    xbus.Read(q); // read slave, passing byte array to store requested data.
    delay(10);
  }   
</code>

<WRAP center round info 90%>
The Read function will only write the 'SetBusRequest' configuration to the slave if required. If the masters configuration is not changed no configuration data is rewritten to the slaves configuration memory. This to prevent useless data transfer. 
</WRAP>

<WRAP center round important 90%>
Due to not rewriting the 'SetBusRequest' configuration on each Read, there could be an issue when the I2C network contains multiple masters! 

If multiple masters are on the same I2C bus, there could be issues where the 'SetBusRequest' configuration on the slave is not in sync with one of the masters. This would only happen if one master changes the slaves configuration and a secondary master Reads from this slave afterwards not rewriting it's own 'SetBusRequest' configuration.

This can be fixed by using the 'Write' function writing an empty byte array to the slaves memory, thereby updating the slaves configuration memory. 
</WRAP>

==== Downloads ====
  * Download full masters library code + example: {{ :xnorit:public:dependencies:xnorbus:arduinoi2cmastertest.rar |}}
  * {{ :xnorit:public:dependencies:xnorbus:xnorbusmaster.h | xnorbusmaster.h}}
  * {{ :xnorit:public:dependencies:xnorbus:xnorbusmaster1.h | xnorbusmaster1.h}}
  * {{ :xnorit:public:dependencies:xnorbus:xnorbusmaster_v2.zip |}}  <color #22b14c>** Added ECC checksum to communication protocol. Only compatible with XnorbusSlave v2! **</color>