Fixes #179 - I2C tutorial added by mittalshravika · Pull Request #181 · tessel/t2-docs

mittalshravika · 2017-09-04T14:12:53Z

Fixes #179. I2C tutorial with relevant code and fritzing diagram added.

HipsterBrown

This is a great start! I would really like to learn more about why certain values are used and how the 12 bit conversion works in the sample code. Think about reading that code with no knowledge of working with hardware, and how would a reader apply this to another I2C project.

For the sample code, how could we continually read values while the user interacts with the Tessel?

HipsterBrown · 2017-09-05T14:03:55Z

Tutorials/i2c.md

+});
+```
+
+[Datasheet for accelerometer module](http://www.nxp.com/docs/en/data-sheet/MMA8452Q.pdf)


Can you include a link to a resource where folks can learn more about I2C communication, i.e. SparkFun?

Thanks a lot for the reviews!! We will update the PR with the requested changes.

The link to sparkfun for I2C Communication has been added.

HipsterBrown · 2017-09-05T14:06:57Z

Tutorials/i2c.md

+
+// Connect to device
+var port = tessel.port.A; // Select Port A of Tessel
+var slaveAddress = 0x1D; // Specefic for accelerometer module


Where did you find this address? From somewhere in the datasheet? How can readers discover this as well?

This has been added.

HipsterBrown · 2017-09-05T14:13:25Z

Tutorials/i2c.md

+i2c.read(numBytesToRead, function (error, dataReceived) {
+
+  // Print data received (buffer of hex values)
+  console.log('Buffer returned by I2C slave device ('+slaveAddress.toString(16)+'):', dataReceived);


What should I expect back from this read? Would anything come back from this component?

HipsterBrown · 2017-09-05T14:14:10Z

Tutorials/i2c.md

+});
+
+// Read/Receive data over I2C using i2c.transfer
+i2c.transfer(new Buffer([0x0D]), numBytesToRead, function (error, dataReceived) {


Why did you choose to use 0x0D for this Buffer value?

This has been added.

HipsterBrown · 2017-09-05T14:14:40Z

Tutorials/i2c.md

+i2c.transfer(new Buffer([0x0D]), numBytesToRead, function (error, dataReceived) {
+
+    // Print data received (buffer of hex values)
+  console.log('Buffer returned by I2C slave device ('+slaveAddress.toString(16)+'):', dataReceived);


What could I expect to be logged here?

This has been added.

HipsterBrown · 2017-09-05T14:17:16Z

Tutorials/i2c.md

+    //Create a blank array for the output
+    var out=[];
+    for (var i=0;i<3;i++)
+    {


This bracket should be on the same line as the for statement, which doesn't need to be so condensed:

for (var i = 0; i < 3; i++) { // rest of the iterating code }

Also why are only 3 iterations needed to read this output Buffer?

This has been added.

HipsterBrown · 2017-09-05T14:19:46Z

Tutorials/i2c.md

+//Now, try to print the accelerometer data using i2c.transfer
+i2c.transfer(new Buffer([0x01]), 6, function (error, dataReceived) {
+
+    // Print data received (buffer of hex values)


This comment is a little misleading, because the error is not a "buffer of hex values" to be printed. If there is an error, when you throw it, the program stops with the error message and stack trace as the output.

The comment has been removed.

HipsterBrown · 2017-09-05T14:23:15Z

Tutorials/i2c.md

+    for (var i=0;i<3;i++)
+    {
+      //iterating for the x, y, z values
+      var gCount=(dataReceived[i*2] << 8) | dataReceived[(i*2)+1]; //Converting the 8 bit data into a 12 bit


What does gCount mean or stand for? Can you add a paragraph after the sample code to explain how converting 8 bit data into 12 bit data works?

@Frijol Could you please help us out as to what is exactly happening in this part of the code? We tried understanding it from our part but couldnt do so.

HipsterBrown · 2017-09-05T14:24:22Z

Tutorials/i2c.md

+      //iterating for the x, y, z values
+      var gCount=(dataReceived[i*2] << 8) | dataReceived[(i*2)+1]; //Converting the 8 bit data into a 12 bit
+      gCount=gCount >> 4;
+      if (dataReceived[i*2] > 0x7F) 


What does the 0x7F value mean? Why do we care if our dataRecieved Buffer has a value greater than 0x7F?

0x7F in decimal is 127 and it could not be found anywhere in the data sheet as well, What is the significance of this here?

HipsterBrown · 2017-09-05T14:25:26Z

Tutorials/i2c.md

+      {
+          gCount = -(1 + 0xFFF - gCount); // Transform into negative 2's complement
+      }
+        out[i] = gCount / ((1<<12)/(2*2));


What is happening here?

mittalshravika · 2017-09-11T18:14:22Z

@HipsterBrown, @Frijol, the changes requested have been added expect a few which we have doubt in. Could you please look into the same and help us out with the rest of the changes left.

HipsterBrown · 2017-09-11T19:07:08Z

Tutorials/i2c.md

+
+// Now, try to print the accelerometer data using i2c.transfer
+// The register address for OUT_X_MSB is 0x01. This can be found at Page 19 of https://www.nxp.com/docs/en/data-sheet/MMA8452Q.pdf
+// 6 Bytes are used for pairwise MSB and LSB of the x,y and z axis


What do MSB and LSB stand for? What do mean by "used for pairwise MSB and LSB"?

HipsterBrown · 2017-09-11T19:13:35Z

@Frijol Do you think the I2C section of the "Communication Protocols" tutorial should be updated to link to this new tutorial? how much sample code do we keep in that older section?

@mittalshravika
Once you get some clarity from @Frijol, could you add a paragraph (before or after the sample code) about the converting the data returned for each axis from 8-bit to 12-bit and creating the final values being logged. Adding a screenshot or sample of the final output, like you included in the issue, at the end will be helpful for readers to know what to expect at the end.

mittalshravika · 2017-09-11T19:16:34Z

Sure, I will add a section about the process. Thanks a lot for the reviews!!

Frijol · 2017-09-17T14:53:18Z

Yes, a link there would be very helpful! @HipsterBrown I'm not sure what you're referring to with "older section"– do you mean the code sample in the communication protocols file itself? I believe it has been updated to latest standards. Are you suggesting we replace the example code that's there with a link to the tutorial?

HipsterBrown · 2017-09-18T14:07:44Z

Are you suggesting we replace the example code that's there with a link to the tutorial?

@Frijol Potentially, yes. I guess the sample code in the Communication Protocols section is helpful for explaining the concept.

brihijoshi · 2017-09-26T07:46:17Z

@HipsterBrown @Frijol The edited commented code has been added :)

We will add the sample output for the code and run the build for the gitbooks.

Please review 😄

mittalshravika · 2017-09-26T15:27:51Z

@HipsterBrown @Frijol The sample output has also been added. Please review the same.

Frijol

This is a strong start! My comments are largely based on the assumption that the reader of this tutorial will want very thorough explanation– ideally, someone new to programming and electronics could read it and understand.

Frijol · 2017-09-28T20:12:31Z

Tutorials/i2c.md

+
+I2C is a simple-to-use communication protocol which can have more than one master, with the upper bus speed defined, and only two wires with pull-up resistors are needed to connect almost _unlimited_ number of I2C devices.
+
+Each slave device has a unique address. Transfer from and to master device is serial and it is split into 8-bit packets. All these simple requirements make it very simple to implement I2C interface even with cheap micro-controllers that have no special I2C hardware controller. You only need 2 free I/O pins and few simple i2C routines to send and receive commands.


typos: micro-controllers > microcontrollers; i2C > I2C

Frijol · 2017-09-28T20:12:51Z

Tutorials/i2c.md

+
+Each slave device has a unique address. Transfer from and to master device is serial and it is split into 8-bit packets. All these simple requirements make it very simple to implement I2C interface even with cheap micro-controllers that have no special I2C hardware controller. You only need 2 free I/O pins and few simple i2C routines to send and receive commands.
+
+Let us get the accelerometer values using the I2C protocol. We would be using the [accel-mma84](https://www.seeedstudio.com/Tessel-Accelerometer-Module-p-2223.html)


We would > We will

Frijol · 2017-09-28T20:13:32Z

Tutorials/i2c.md

+
+Each slave device has a unique address. Transfer from and to master device is serial and it is split into 8-bit packets. All these simple requirements make it very simple to implement I2C interface even with cheap micro-controllers that have no special I2C hardware controller. You only need 2 free I/O pins and few simple i2C routines to send and receive commands.
+
+Let us get the accelerometer values using the I2C protocol. We would be using the [accel-mma84](https://www.seeedstudio.com/Tessel-Accelerometer-Module-p-2223.html)


The accel-mma84 what? The MMA84 accelerometer integrated sensor?

Or would it be more useful to say, the Tessel Accelerometer Module?

Would be a good idea to link to the MMA84 datasheet regardless as it will be useful for someone following along

Frijol · 2017-09-28T20:14:43Z

Tutorials/i2c.md

+
+Let us get the accelerometer values using the I2C protocol. We would be using the [accel-mma84](https://www.seeedstudio.com/Tessel-Accelerometer-Module-p-2223.html)
+
+![Fritzing Diagram](http://i.imgur.com/zK4U4S3.png)https://github.com/276linesofCode/Codes-Ideas/edit/master/tut-i2c.md#fork-destination-box


Is the Github link supposed to be there?

Frijol · 2017-09-28T20:37:13Z

Tutorials/i2c.md

+// Connect to device
+var port = tessel.port.A; // Use the SCL/SDA pins of Port A
+
+//This address of the Slave has been taken from https://github.com/tessel/accel-mma84/blob/master/index.js#L15


Typo: space after //

Frijol · 2017-09-28T21:35:19Z

Tutorials/i2c.md

+        positive. If it is negative (checked using 0x7F, which is the maximum possible number that can be made from 7 bits), the if condition changes
+        it to a 2's complement form, thus making it positive and adding a "-" sign in front of it.
+
+        Lastly, normalise the coordinate to get a value between 0 and 1, dividing the gCount by 2^10.


normalise > normalize

Frijol · 2017-09-28T21:35:36Z

Tutorials/i2c.md

+        positive. If it is negative (checked using 0x7F, which is the maximum possible number that can be made from 7 bits), the if condition changes
+        it to a 2's complement form, thus making it positive and adding a "-" sign in front of it.
+
+        Lastly, normalise the coordinate to get a value between 0 and 1, dividing the gCount by 2^10.


"dividing the gCount" > "dividing gCount"

Frijol · 2017-09-28T21:47:24Z

Tutorials/i2c.md

+
+      */
+
+      for (var i=0;i<3;i++){


Comment: three iterations for the three coordinates

Frijol · 2017-09-28T21:48:08Z

Tutorials/i2c.md

+
+      /*
+
+      The for loop is iterated 3 times, in order to extract the x,y,z values.


In my opinion, clearer to break this out into line by line comments in the code

Frijol · 2017-09-28T21:54:23Z

Tutorials/i2c.md

+        var gCount=(dataReceived[i*2] << 8) | dataReceived[(i*2)+1];
+        gCount=gCount >> 4;
+
+        // 127 is checking whether we have a 0 or a 1 at the first position - basically its sign.


Can you give this a bit more explanation? Where does 127 come from, specifically? Tie back to 2's complement

mittalshravika · 2017-09-29T18:30:55Z

@Frijol, we have made all the changes you had requested. You may review the same.

Frijol

All right, on to the more thorough critique ;)

Frijol · 2017-10-03T15:49:54Z

Tutorials/i2c.md

@@ -0,0 +1,110 @@
+# I2C
+
+I2C is a simple-to-use communication protocol which can have more than one master, with the upper bus speed defined, and only two wires with pull-up resistors are needed to connect almost _unlimited_ number of I2C devices.


strike "simple-to-use"– that's a value judgment and might make some readers think along the lines of "well, I couldn't figure it out..". You can say it's "designed to be simple" if you want, but I think the rest of your description (two wires, unlimited devices) is more helpful

Frijol · 2017-10-03T15:51:50Z

Tutorials/i2c.md

+
+I2C is a simple-to-use communication protocol which can have more than one master, with the upper bus speed defined, and only two wires with pull-up resistors are needed to connect almost _unlimited_ number of I2C devices.
+
+Each slave device has a unique address. Transfer from and to master device is serial and it is split into 8-bit packets. All these simple requirements make it very simple to implement I2C interface even with cheap microcontrollers that have no special I2C hardware controller. You only need 2 free I/O pins and few simple I2C routines to send and receive commands.


"Transfer from and to master device is serial and it is split into.." -> "Information transfer to and from the master device is serial. Data is split into 8-bit packets."

Frijol · 2017-10-03T15:53:35Z

Tutorials/i2c.md

+
+I2C is a simple-to-use communication protocol which can have more than one master, with the upper bus speed defined, and only two wires with pull-up resistors are needed to connect almost _unlimited_ number of I2C devices.
+
+Each slave device has a unique address. Transfer from and to master device is serial and it is split into 8-bit packets. All these simple requirements make it very simple to implement I2C interface even with cheap microcontrollers that have no special I2C hardware controller. You only need 2 free I/O pins and few simple I2C routines to send and receive commands.


Second sentence uses "simple" twice but should ideally avoid it. Something more like "An I2C interface can be implemented even with cheap microcontrollers that have no special I2C hardware controller. The protocol only requires two I/O pins..."

Frijol · 2017-10-03T15:54:32Z

Tutorials/i2c.md

+
+I2C is a simple-to-use communication protocol which can have more than one master, with the upper bus speed defined, and only two wires with pull-up resistors are needed to connect almost _unlimited_ number of I2C devices.
+
+Each slave device has a unique address. Transfer from and to master device is serial and it is split into 8-bit packets. All these simple requirements make it very simple to implement I2C interface even with cheap microcontrollers that have no special I2C hardware controller. You only need 2 free I/O pins and few simple I2C routines to send and receive commands.


"...a few simple I2C routines" – what's a more descriptive word than "simple"? Do you mean that they require few lines of code? That the logic is easily parsed? Is the descriptor helpful, or superfluous?

Frijol · 2017-10-03T15:55:41Z

Tutorials/i2c.md

+
+Each slave device has a unique address. Transfer from and to master device is serial and it is split into 8-bit packets. All these simple requirements make it very simple to implement I2C interface even with cheap microcontrollers that have no special I2C hardware controller. You only need 2 free I/O pins and few simple I2C routines to send and receive commands.
+
+Let us get the accelerometer values using the I2C protocol. We will be using the [The Tessel Accelerometer](https://www.seeedstudio.com/Tessel-Accelerometer-Module-p-2223.html)


Beginning the phrasing with "In this tutorial..." and a description of the end result of the tutorial might be more clear here

Frijol · 2017-10-03T16:31:57Z

Tutorials/i2c.md

+
+      The x,y, and z accelerometer values are stored in their respective OUT_MSB and OUT_LSB registers as negative values i.e. their 2's       complement form. 
+      Therefore in order to obtain the correct values, check whether the most significant bit of the OUT_MSB is 1 or 0 i.e whether the         coordinate value is negative or positive. 
+      If it is negative (checked using 0x7F, which is the maximum possible number that can be made from 7 bits), the if condition             changes it to a 2's complement form, thus making it positive and adding a "-" sign in front of it.


Would it be clearer to use > 0b01111111 ?

Frijol · 2017-10-03T16:33:09Z

Tutorials/i2c.md

+### Sample Ouput
+
+![output](https://i.imgur.com/Dg462Jf.jpg)
+


Great! Can you think of a bonus question to ask?

Frijol · 2017-10-03T16:33:22Z

Tutorials/i2c.md

+
+![output](https://i.imgur.com/Dg462Jf.jpg)
+
+[Datasheet for accelerometer module](http://www.nxp.com/docs/en/data-sheet/MMA8452Q.pdf)


These seem like a separate section, not part of Sample Output

Frijol · 2017-10-03T16:37:53Z

Tutorials/i2c.md

+
+### Sample Ouput
+
+![output](https://i.imgur.com/Dg462Jf.jpg)


This is your Fritzing diagram, not output

Frijol · 2017-10-03T16:38:48Z

Tutorials/i2c.md

+      console.log('The x, y, z values are :',out);
+
+  });
+```


Does your code actually work & respond appropriately when run? I think you're missing a crucial step– look up SYSMOD in the datasheet

mittalshravika · 2017-10-04T03:20:28Z

Thanks a lot for the reviews!! Will make the changes shortly.

I2C tutorial added

d601803

HipsterBrown requested changes Sep 5, 2017

View reviewed changes

Requested changes added

df50c18

HipsterBrown reviewed Sep 11, 2017

View reviewed changes

Added commented code

6b0e741

Update i2c.md

537b8cc

Frijol requested changes Sep 28, 2017

View reviewed changes

mittalshravika added 4 commits September 29, 2017 16:21

Made the changes requested

334c440

Documentation made more clearly on 2's complement

0980466

Line by line comments added

56a8e7a

Changes in spacing

904d788

Frijol requested changes Oct 3, 2017

View reviewed changes


		I2C is a simple-to-use communication protocol which can have more than one master, with the upper bus speed defined, and only two wires with pull-up resistors are needed to connect almost _unlimited_ number of I2C devices.

		Each slave device has a unique address. Transfer from and to master device is serial and it is split into 8-bit packets. All these simple requirements make it very simple to implement I2C interface even with cheap micro-controllers that have no special I2C hardware controller. You only need 2 free I/O pins and few simple i2C routines to send and receive commands.


		Each slave device has a unique address. Transfer from and to master device is serial and it is split into 8-bit packets. All these simple requirements make it very simple to implement I2C interface even with cheap micro-controllers that have no special I2C hardware controller. You only need 2 free I/O pins and few simple i2C routines to send and receive commands.

		Let us get the accelerometer values using the I2C protocol. We would be using the [accel-mma84](https://www.seeedstudio.com/Tessel-Accelerometer-Module-p-2223.html)


		Let us get the accelerometer values using the I2C protocol. We would be using the [accel-mma84](https://www.seeedstudio.com/Tessel-Accelerometer-Module-p-2223.html)

		![Fritzing Diagram](http://i.imgur.com/zK4U4S3.png)https://github.com/276linesofCode/Codes-Ideas/edit/master/tut-i2c.md#fork-destination-box


		/*

		The for loop is iterated 3 times, in order to extract the x,y,z values.

		@@ -0,0 +1,110 @@
		# I2C

		I2C is a simple-to-use communication protocol which can have more than one master, with the upper bus speed defined, and only two wires with pull-up resistors are needed to connect almost _unlimited_ number of I2C devices.


		![output](https://i.imgur.com/Dg462Jf.jpg)

		[Datasheet for accelerometer module](http://www.nxp.com/docs/en/data-sheet/MMA8452Q.pdf)

Conversation

mittalshravika commented Sep 4, 2017

Uh oh!

HipsterBrown left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mittalshravika Sep 11, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mittalshravika commented Sep 11, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

HipsterBrown commented Sep 11, 2017

Uh oh!

mittalshravika commented Sep 11, 2017

Uh oh!

Frijol commented Sep 17, 2017

Uh oh!

HipsterBrown commented Sep 18, 2017

Uh oh!

brihijoshi commented Sep 26, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mittalshravika commented Sep 26, 2017

Uh oh!

Frijol left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mittalshravika Sep 11, 2017 •

edited

Loading

brihijoshi commented Sep 26, 2017 •

edited

Loading