Need to document how library expects column & row pins to be wired to matrix

[bperrybap]

Currently there does not seem to be any documentation that describes how the HTK1633 row and column pins are expected to be wired up to the matrix. There are many ways that this could be done so it needs to be documented. While this isn't an issue for the products that are full boards with the matrix soldered on, it is an issue for users of the Adafruit 16x8 LED Matrix Driver Backpack - HT16K33 Breakout http://www.adafruit.com/products/1427

The wiring for the 8x8 is funky because of columns connections being rotated around.

The 8x16 wiring is funky because it is really wired up as 16x8 matrix and not a 8x16 matrix. I bring up this 8x16 vs 16x8 issue because the current library code has a 8x16 class yet all the products call it a 16x8 matrix. It isn't just a matter of saying it could be either depending on your point of view as that isn't' really the case, particularly when it comes to physical wiring and orientations. I commented on this in issue #7

So what would be nice would be to document the needed wiring. I'd suggest in the code where the class is so they are kept together and won't get lost. Then have something in a readme somewhere to point users to the code for how to wire things up.

Actual hkt1633 connection wiring to the matrix should not be confused with orientation as they are not the same.

Here is the current needed wiring and default orientation for the 8x16 class:

  c7 c6 c5 c4 c3 c2 c1 c0
a0
a1
a2
a3
a4
a5
a7
a8
a9
a10
a11
a12
a13
a14
a15

Here is the very same wiring used for a new 16x8 class It represents the default orientation for a new 16x8 class.

  a0 a1 a2 a3 a4 a5 a6 a7 a8 a9 a10 a11 a12 a13 a14 a15
c0
c1
c2
c3
c4
c5
c7

Here is the current needed wiring and default orientation for the 8x8 class: (the column wiring is wrapped around)

  a1 a2 a3 a4 a5 a6 a7 a0 
c0
c1
c2
c3
c4
c5
c7

Not sure why the 8x8 wiring is so screwy, perhaps it made the layout easier for the PCBs that include the matrix. It is no fun when using the Adafruit 16x8 LED Matrix Driver Backpack, unless you know to wire it up that way.

Because of the wrapped column wiring expected in the 8x8 class, its wiring is incompatible with the 8x16/16x8 wiring.

It would really nice if the wiring was documented for users of the Adafruit 16x8 LED Matrix Driver Backpack. I'd suggest putting a table like the ones I showed above with some explanation that the An lines are the anodes and the Cn lines are the cathodes and the figure represents the wiring as well as the default orieintation with 0,0 being the upper left corner and x values increase to the right and y values increase moving down.

[robertcasanova]

Thx for this explanation, i don't understand why matrix appear on wrong orientation until I read this.

[caternuson]

Use the HT16K33 datasheet when using the breakout (PID 1427). Specific wiring would depend on usage.

For the other products, the wiring may be a result of routing requirements, etc. But the library should abstract those away so you don't need to worry about it.

[bperrybap]

@caternuson It appears you are not fully understanding or appreciating the issue, particularly for users of the 1427 breakout board. The current library does not abstract this away. As it is now, the user must wire up the matrix the particular way the library expects it to be wired up and the library never documents how it expects the columns and rows to be wired up. Complicating matters is that there is a screwy wiring requirement for the 8x8 class that is specific to the Adafruit 8x8 matrix products likely for layout reasons. Also the 8x16 matrix is not addressing the rows and columns the same way as the 8x8. The library sometimes uses the chip column pins for columns and sometimes for rows. Sometimes the chip column pins must be reversed to go highest to lowest instead of the normal lowest to highest order. And for the 8x8 class, not only are the chip column pins used for rows and the chip row pins used for columns but column order is screwy and rotated around to be a1 a2 a3 a4 a5 a6 a7 a0 instead of natural order.

All this is why the wiring needs to documented. Without the documentation, the user of the 1427 breakout board will have to spend lots of time to figure all this out.

The user has to know how the library expects the matrix to be wired up. This is something that at least needs to be documented. I have commented on these issues for several years now. https://github.com/adafruit/Adafruit_LED_Backpack/issues/7#issuecomment-83227027 https://github.com/adafruit/Adafruit_LED_Backpack/issues/13#issue-40024746 It is time to at least document this. It could be as simple as big comment block in the header file.

[caternuson]

Is the issue the lack of a generic class for use with the breakout?

The other classes are meant for use with specific products based on the HT16K33. Not the generic breakout.

[bperrybap]

Is the issue the lack of a generic class for use with the breakout?

Kind of but not really.

The issue is that the library currently assumes a very specific wiring that is not documented. The expected wiring is not what one expects as it is not as shown in the data sheet and is inconsistent between 8x16 and 8x8 and then the 8x8 is really funky given the library works around a funky layout issue in that 8x8 matrix product.

So not only is the specific wiring that must be used not documented anywhere, but there is also no mention anywhere that library has hard coded to use a funky wiring expectation for certain specific products that is different from what is shown in the datasheet and what a person would expect.

It is real problem for using products like the HT16K33 Breakout PRODUCT ID: 1427 On its product page: https://www.adafruit.com/product/1427 It says:

Wire up any matrix you want and use our handy library to write to the display however you wish. and

This chip is rock solid, has Arduino & Pi example code written for it and is easy to use.

And then there is a link to this library. So the big issue becomes it isn't possible do that since the user must know how to wire up the LED matrix to able to use this library but it is not documented anywhere and the wiring is not "normal" or what would be expected. The lack of documenting the wiring makes it not easy to use since the user must spend the time to go through the code and the board schematics of the other products to figure out the needed wiring.

Again, why not add a comment in the code or header file that explains the expected/required wiring? And perhaps even put the same wiring information on the product web page so that how to wire it up is obvious.

In the original post of this issue I created, I even posted the two wiring tables for the 8x16 and the 8x8 class.

[caternuson]

If you are using the LED backpack in a generic way, like with your own LED product, then you only want to use the base Adafruit_LEDBackpack class as shown in this example: https://github.com/adafruit/Adafruit_LED_Backpack/blob/master/examples/HT16K33/HT16K33.ino

All other classes are for specific Adafruit LED products and their associated wiring. The PCB files for those would be the documentation for their specific wiring to the HT16K33.

[bperrybap]

Again, the missing documentation is for the SOFTWARE library not the hardware. It is the library wiring expectations and how the row and com pins must be wired that is not documented. Even if using the Adafruit_LEDbackpack base class the user still needs to know how to wire up the row and column pins as there are several ways to do this and only one will be the correct way to get the proper memory mapping to LEDs to show up on the display correctly.

The user needs to know how to wire up the pins to get the memory to LED mapping to work correctly. Consider this, the chip datasheet uses the term "Row" pins but with this library the "Row" pins don't always control the row of which LED is lit up; sometimes they control the column of the LED.

I strongly believe that expecting your customers to go through the PCB files and weed through the library code to determine how to wire up their 870, 871, 872 products to your 1472 product is unreasonable. Particularly when just a few lines of added comments to your header files and few lines of comments in some of the example sketches and perhaps a small note on the product page about it or to see the comments in the code could clear all this up.

And while your customers could use the Adafruit_LEDbackpack base class, they still need to know how to wire up the row and com pins to get the memory map to physical LEDs correct. And on top of that if they use just the base class would lose out on pretty much all the usefulness of the library since they won't get any of the GFX library functions where is where the real value is.

Even that generic HT16K33/HT16K33.ino sketch needs a comment indicating how to wire up the matrix.

It sounds like guys are not concerned about being helpful for your customers that use use the 1427 breakout product with products like 870, 871, and 872. That is definitely your prerogative but I just don't understand the resistance of providing a small amount of information/documentation to help out your customers that want to use these products.

[caternuson]

It sounds like guys are not concerned about being helpful for your customers that use use the 1427 breakout product with products like 870, 871, and 872.

If you are using one of those products, follow this guide for assembly: https://learn.adafruit.com/adafruit-led-backpack/0-8-8x8-matrix-assembly and use this example for Arduino code: https://github.com/adafruit/Adafruit_LED_Backpack/blob/master/examples/matrix8x8/matrix8x8.ino In general, you do not need to know anything about the actual wiring between the HT16K33 and the LED module.

[mihow]

I can confirm that you do need to know the specific wiring that this library expects. I had to look at the source code to know what to wire where. The HT16K33 page should not link to this library if you aren’t willing to update the documentation. I bought a dozen of these thinking they would be supported by this recommended library. By the time I figured out the wiring I ended up using my own custom code instead. Other adafruit libraries have been very plug and play and helpful with the hardware that recommends them.

https://www.adafruit.com/product/1427

Thanks for your support!

On Sat, Sep 25, 2021 at 10:12 AM Carter Nelson @.***> wrote:

It sounds like guys are not concerned about being helpful for your customers that use use the 1427 breakout product with products like 870, 871, and 872.

If you are using one of those products, follow this guide for assembly: https://learn.adafruit.com/adafruit-led-backpack/0-8-8x8-matrix-assembly and use this example for Arduino code:

https://github.com/adafruit/Adafruit_LED_Backpack/blob/master/examples/matrix8x8/matrix8x8.ino In general, you do not need to know anything about the actual wiring.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/adafruit/Adafruit_LED_Backpack/issues/19#issuecomment-927153343, or unsubscribe https://github.com/notifications/unsubscribe-auth/AABGTX3KRDHK2TL3KDKEMIDUDX7JLANCNFSM4A6EEMUA . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

[caternuson]

@mihow What actual LED product were you using along with the PID 1427 breakout?

[ladyada]

https://github.com/adafruit/Adafruit_LED_Backpack/blob/master/examples/HT16K33/HT16K33.ino is the demo for a 'bare' chip - you will just write to each bit in memory

[mihow]

Thanks for the example. I was using this with generic 4" seven segment LED displays. I think part of the appeal of this library was the nice looking " matrix.print(num)" functions to display a letter or number, because that's tedious code to write on your own for segmented displays. So I think what me and @bperrybap were hoping for was a diagram like this one that shows which pins to which segments the library is expecting, in order to use those convenience functions.

[image: image.png]

On Sat, Sep 25, 2021 at 10:33 AM Carter Nelson @.***> wrote:

@mihow https://github.com/mihow What actual LED product were you using along with the PID 1427 breakout?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/adafruit/Adafruit_LED_Backpack/issues/19#issuecomment-927156118, or unsubscribe https://github.com/notifications/unsubscribe-auth/AABGTX6D4QDJSYBBIDRVOETUDYBVXANCNFSM4A6EEMUA . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

[mihow]

Sorry it's also been 5 years since I used this for a project! I wish I had updated the docs on my own at that point in time.

On Sat, Sep 25, 2021 at 11:04 AM Michael Bunsen @.***> wrote:

Thanks for the example. I was using this with generic 4" seven segment LED displays. I think part of the appeal of this library was the nice looking " matrix.print(num)" functions to display a letter or number, because that's tedious code to write on your own for segmented displays. So I think what me and @bperrybap were hoping for was a diagram like this one that shows which pins to which segments the library is expecting, in order to use those convenience functions.

[image: image.png]

On Sat, Sep 25, 2021 at 10:33 AM Carter Nelson @.***> wrote:

@mihow https://github.com/mihow What actual LED product were you using along with the PID 1427 breakout?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/adafruit/Adafruit_LED_Backpack/issues/19#issuecomment-927156118, or unsubscribe https://github.com/notifications/unsubscribe-auth/AABGTX6D4QDJSYBBIDRVOETUDYBVXANCNFSM4A6EEMUA . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

[caternuson]

@mihow I think in your case the confusion stems from attempting to reuse the classes written for specific Adafruit products with your HT16K33 breakout+generic LED setup. If you did not also duplicate the Adafruit wiring exactly, then it would probably not work as expected. The actual LED product may have had different wiring than those used by Adafruit as well.

Is anyone here using anything other than PID 1427? https://www.adafruit.com/product/1427 If so, please specify.

[ladyada]

you'd follow the schematics here to match the subclasses https://learn.adafruit.com/adafruit-led-backpack/downloads