Add binding for IS31FL3730 LED driver #1930

richlander · 2022-09-22T15:10:39Z

Used by:

Port of https://github.com/pimoroni/microdot-phat.

Microsoft Reviewers: Open in CodeFlow

gfoidl

I see the draft, but hope you're OK with early feedback.

src/devices/Is31fl3730/Bonnet5x7x6.cs

gfoidl · 2022-09-24T18:59:23Z

src/devices/Is31fl3730/Is31fl3730.cs

+
+            if (CurrentSetting > 0)
+            {
+                _i2cDevice.Write(new byte[] { LIGHTING_EFFECT_REGISTER, (byte)CurrentSetting });


I2CDevice has an overload that takes a ROS

iot/src/System.Device.Gpio/System/Device/I2c/I2cDevice.cs

Line 62 in a914669

public abstract void Write(ReadOnlySpan<byte> buffer);

, so this temp. allocation of the byte-array can be avoided.

Suggested change

_i2cDevice.Write(new byte[] { LIGHTING_EFFECT_REGISTER, (byte)CurrentSetting });

_i2cDevice.Write(stackalloc byte[] { LIGHTING_EFFECT_REGISTER, (byte)CurrentSetting });

Same below.

gfoidl · 2022-09-24T19:02:50Z

src/devices/Is31fl3730/Is31fl3730.cs

+            if (value > 0)
+            {
+                buffer.AsSpan().Fill(255);
+            }
+            else
+            {
+                buffer.AsSpan().Fill(0);
+            }


Suggested change

if (value > 0)

{

buffer.AsSpan().Fill(255);

}

else

{

buffer.AsSpan().Fill(0);

}

buffer.AsSpan().Fill(value > 0 ? 255 : 0);

More a matter of taste, but IL-size is also smaller (which I don't believe is a criteria here).

Or

Suggested change

if (value > 0)

{

buffer.AsSpan().Fill(255);

}

else

{

buffer.AsSpan().Fill(0);

}

if (value > 0)

{

buffer.AsSpan().Fill(255);

}

else

{

buffer.AsSpan().Clear();

}

Clear is (in general) better than Fill(0) (better optimization in the implementation).

just FYI we prefer cleaner code to microoptimizations in this code-base except where it really matters. Reducing allocations - yes, microoptimization - not quite (except maybe direct GPIO operations). Here I2C transmission itself will likely take more than 99% of the time and this won't make any observable difference. I'd rather write this code as:

buffer.AsSpan().Fill(value > 0 ? 255 : 0);

gfoidl · 2022-09-24T19:07:46Z

src/devices/Is31fl3730/Is31fl3730.cs

+        private void Write(byte address, byte[] value)
+        {
+            byte[] data = new byte[value.Length + 1];
+            data[0] = address;
+            value.CopyTo(data.AsSpan(1));
+            _i2cDevice.Write(data);
+        }


Suggested change

private void Write(byte address, byte[] value)

{

byte[] data = new byte[value.Length + 1];

data[0] = address;

value.CopyTo(data.AsSpan(1));

_i2cDevice.Write(data);

}

private void Write(byte address, ReadOnlySpan<byte> value)

{

Debug.Assert(value.Length < 256);

Span<byte> data = stackalloc byte[value.Length + ];

data[0] = address;

value.CopyTo(data.Slice(1));

_i2cDevice.Write(data);

}

Avoids the temp. allocation.

gfoidl · 2022-09-24T19:08:07Z

src/devices/Is31fl3730/Is31fl3730.cs

+
+        private void Write(byte address, byte value)
+        {
+            _i2cDevice.Write(new byte[] { address, value });


Suggested change

_i2cDevice.Write(new byte[] { address, value });

_i2cDevice.Write(stackalloc byte[] { address, value });

Co-authored-by: Günther Foidl <gue@korporal.at>

Ellerbach

Couple of comments for this very nice addition :-)

Ellerbach · 2022-10-04T08:02:42Z

src/devices/Is31fl3730/BreakoutPair5x7.cs

+        /// <param name="i2cDevice">The <see cref="System.Device.I2c.I2cDevice"/> to create with.</param>
+        public BreakoutPair5x7(I2cDevice? i2cDevice = null)
+        {
+            _i2cDevice = i2cDevice is not null ? i2cDevice : I2cDevice.Create(new(1, Is31fl3730.DefaultI2cAddress));


We're not using this pattern and always leave the creation of the I2cDevice to the caller. Reason is because bus may be different, ownership as well and finally adaptors like FT4222 or Arduino. So don't pass the null as default and raise and exception if null.

Ellerbach · 2022-10-04T08:03:44Z

src/devices/Is31fl3730/BreakoutPair5x7.cs

+        {
+            _is31fl3730?.Dispose();
+            _is31fl3730 = null!;
+            _i2cDevice?.Dispose();


with the pattern we are using, as we don't create I2cDevice in the bindings, we don't dispose them. It's to the caller to take care of this.

Ellerbach · 2022-10-04T08:05:43Z

src/devices/Is31fl3730/Is31fl3730.cs

+    {
+        // Function register
+        // table 2 in datasheet
+        private const byte CONFIGURATION_REGISTER = 0x0;


rather than using constants, use a Register.cs file with enums in there being internal. Like this, you will be able to keep the register names like they are (all uppercase). And it's much better than constants.

Ellerbach · 2022-10-04T08:10:37Z

src/devices/Is31fl3730/MatrixMode.cs

+        /// <summary>
+        /// Represents a 8x8 LED matrix.
+        /// </summary>
+        Size8x8,


As you are using explicit check of MatrixMode > 0 earlier, make the first element explicit to 0

src/devices/Is31fl3730/Is31fl3730.cs

Ellerbach · 2022-10-04T08:15:09Z

src/devices/Is31fl3730/Is31fl3730.cs

+        /// </summary>
+        public void UpdateDecimalPoint(int matrix, int value)
+        {
+            int matrixOneMask = 128;


const for those 2 would be better as you are using them like this

Ellerbach · 2022-10-04T08:16:39Z

src/devices/Is31fl3730/Is31fl3730.cs

+        {
+            Span<byte> data = stackalloc byte[value.Length + 1];
+            data[0] = address;
+            value.CopyTo(data[1..]);


I guess you have to adjust the imports to add the new range (I love them btw :-))

Is there guidance on how to make this work for .NET Standard 2.0? Is this the right pattern? https://www.meziantou.net/how-to-use-csharp-8-indices-and-ranges-in-dotnet-standard-2-0-and-dotn.htm

I went with this: d82f7ff

Ellerbach · 2022-10-04T08:17:44Z

src/devices/Is31fl3730/Is31fl3730.cs

+        /// <param name="x">The x dimension for the LED.</param>
+        /// <param name="y">The y dimension for the LED.</param>
+        /// <param name="value">The value to write.</param>
+        public void WriteLed(int matrix, int x, int y, int value)


Something to consider as you only have 2 matrix: use an enum rather than an int?

Ellerbach · 2022-10-04T08:19:48Z

src/devices/Is31fl3730/MicroDotphat30x7.cs

+        /// <param name="i2cDevice">The <see cref="System.Device.I2c.I2cDevice"/> to create with.</param>
+        public BreakoutPair5x7(I2cDevice? i2cDevice = null)
+        {
+            _i2cDevice = i2cDevice is not null ? i2cDevice : I2cDevice.Create(new(1, Is31fl3730.DefaultI2cAddress));


same remark as for the other one, we don't create I2cDevice from the bindings.

Ellerbach · 2022-10-04T08:20:35Z

src/devices/Is31fl3730/MicroDotphat30x7.cs

+        {
+            _is31fl3730?.Dispose();
+            _is31fl3730 = null!;
+            _i2cDevice?.Dispose();


And similar as my comment for the other one, no need to dispose as we don't create it in the binding

I followed that guidance, however, when I came to supporting the Micro Dot pHAT, I found that there was a need to specify three I2C addresses. That's a bit of a pain. What do you think?

Here are two constructors: 0d1e95f#diff-c1aa6bb26153d700cceaa57064762e4c6dce51672088c47a5f883ded6f76c12eR28-R47

I'm happy to do whatever you think best. I wanted to demonstrate the UX of the two approaches.

I resolved this.

pgrawehr · 2022-12-25T09:48:49Z

is this very different from #1926? Should the two be completely independent?

richlander · 2023-01-03T17:03:20Z

Yes. They are very different. The two drivers do not work similarly. If you look at the datasheets, you'll see that there very little similarity w/no opportunity for code sharing. Still, good question.

pgrawehr

Looks mostly good. Some general comments:

Documentation of some classes could be improved (was apparently just copy-pasted in some places)
Review the visibility of enums and constants. Ideally, bindings should not expose register numbers and other low-level constants.

pgrawehr · 2023-01-06T08:30:25Z

src/devices/Is31fl3730/Current.cs

+    /// <summary>
+    /// Represents an IS31FL3731 LED Matrix driver
+    /// </summary>
+    public enum Current


Documentation is apparently wrong. Should be something about (maximum?) LED current.

Fixed. I copied the text from the datasheet.

pgrawehr · 2023-01-06T08:31:42Z

src/devices/Is31fl3730/DisplayMode.cs

+    /// <summary>
+    /// Represents an IS31FL3731 LED Matrix driver
+    /// </summary>
+    public enum DisplayMode


Again: This documentation doesn't describe the enum

pgrawehr · 2023-01-06T08:45:34Z

src/devices/Is31fl3730/Is31fl3730.cs

+        public DisplayMode DisplayMode { get; set; }
+
+        /// <summary>
+        /// Enables or disables auto-buggering.


Typo in comment

pgrawehr · 2023-01-06T08:52:35Z

src/devices/Is31fl3730/Is31fl3730.cs

+        /// <param name="x">The x dimension for the LED.</param>
+        /// <param name="y">The y dimension for the LED.</param>
+        /// <param name="value">The value to write.</param>
+        public void Write(int matrix, int x, int y, int value)


Since apparently, value is either 0 or 1, wouldn't it be better to use a bool or a PinValue type? Or is this designed to support displays with colors, too? (The method isn't virtual or from an interface, though)

pgrawehr · 2023-01-06T08:58:22Z

src/devices/Is31fl3730/Is31fl3730.cs

+        /// <summary>
+        /// Brightness of LED matrix (override default value (128; max brightness); set before calling Initialize method).
+        /// </summary>
+        public int Brightness { get; set; }
+
+        /// <summary>
+        /// Full current setting for each row output of LED matrix (override default value (40 mA)); set before calling Initialize method).
+        /// </summary>
+        public Current Current { get; set; }


Is there a reason why we don't allow setting Current and Brightness after Initialization? At the moment, setting these members after initialisation has no effect (not even an exception), but it looks like writing the associated registers should always be possible.

+1, the interest of having such properties is for them to be dynamic, so you can adjust them on the fly without having to call the initialize function

Fixed. Good call.

pgrawehr · 2023-01-06T09:00:28Z

src/devices/Is31fl3730/MatrixValues.cs

+    /// <summary>
+    /// Matrix Values.
+    /// </summary>
+    public static class MatrixValues


Does this need to be public?

Good call. Fixed.

pgrawehr · 2023-01-06T09:03:18Z

src/devices/Is31fl3730/Registers.cs

+    /// <summary>
+    /// Register addresses for the Function Register.
+    /// </summary>
+    public static class FunctionRegister


There's probably no need to make this public.

Good call. Fixed.

pgrawehr · 2023-01-06T09:03:37Z

src/devices/Is31fl3730/Registers.cs

+    /// <summary>
+    /// Register addresses for the Configuration Register.
+    /// </summary>
+    public static class ConfigurationRegister


and this, too.

and each enum should be in its own file

Ellerbach

Few more comments.

src/devices/Display/IMatrix.cs

Ellerbach · 2023-01-06T23:04:54Z

src/devices/Is31fl3730/Current.cs

+        /// <summary>
+        /// 40 mA
+        /// </summary>
+        CmA40 = 0b0,


even if those are just 0, maybe better to align with 4 0 like the rest?

src/devices/Is31fl3730/Current.cs

src/devices/Is31fl3730/DotMatrix.cs

src/devices/Is31fl3730/DotMatrix10x7.cs

src/devices/Is31fl3730/Is31fl3730.cs

Ellerbach · 2023-01-06T23:11:13Z

src/devices/Is31fl3730/Is31fl3730.cs

+        /// <summary>
+        /// Brightness of LED matrix (override default value (128; max brightness); set before calling Initialize method).
+        /// </summary>
+        public int Brightness { get; set; }
+
+        /// <summary>
+        /// Full current setting for each row output of LED matrix (override default value (40 mA)); set before calling Initialize method).
+        /// </summary>
+        public Current Current { get; set; }


+1, the interest of having such properties is for them to be dynamic, so you can adjust them on the fly without having to call the initialize function

src/devices/Is31fl3730/Is31fl3730.cs

Ellerbach · 2023-01-06T23:14:53Z

src/devices/Is31fl3730/Registers.cs

+    /// <summary>
+    /// Register addresses for the Configuration Register.
+    /// </summary>
+    public static class ConfigurationRegister


and each enum should be in its own file

Co-authored-by: Laurent Ellerbach <laurelle@microsoft.com>

richlander · 2023-01-17T04:59:01Z

I'm having some namespace problems, as you can see with 0921724. Any advice on that would be appreciated.

src/devices/Is31fl3730/FunctionRegister.cs

Ellerbach

Thanks, looks great to me now!

richlander · 2023-02-02T17:30:17Z

Thanks for all the help on these bindings. I learned a lot.

pgrawehr · 2023-02-02T19:05:29Z

/azp run dotnet.iot

azure-pipelines · 2023-02-02T19:05:39Z

Azure Pipelines successfully started running 1 pipeline(s).

pgrawehr

LGTM. You might wish to take a look at input validation, though.

pgrawehr · 2023-02-02T19:15:22Z

src/devices/Is31fl3730/Is31fl3730.cs

+        // Set high bit for the 128th item
+        // Set high bit low for the remaining 127 items
+        // And then set lower bits as appropriate, to represent 0-127
+        public void UpdateBrightness(byte value) => Write(Is31fl3730FunctionRegister.Pwm, value);


According to the documentation, not all values are valid (only 0-128). If that's correct, this method should contain some input validation.

Interesting. That's a good point. Fair.

pgrawehr · 2023-02-02T19:16:17Z

src/devices/Is31fl3730/Is31fl3730.cs

+        /// <summary>
+        /// Update current setting for each row output of LED matrix (default value is 40 mA).
+        /// </summary>
+        public void UpdateCurrent(Current value) => Write(Is31fl3730FunctionRegister.LightingEffect, (byte)value);


While we're not doing that everywhere correctly, it would be good to check for valid values here as well. The user could pass any value that is not part of the enum.

richlander and others added 2 commits September 21, 2022 16:15

Binding for IS31FL3731 LED Matrix driver

8299345

Add sample

ccd9b9a

ghost added the area-device-bindings Device Bindings for audio, sensor, motor, and display hardware that can used with System.Device.Gpio label Sep 22, 2022

richlander added 3 commits September 22, 2022 21:27

Update sample

be62d43

Update comments

7b78e6f

Add Matrix5x7 class

f0a1458

gfoidl reviewed Sep 24, 2022

View reviewed changes

richlander and others added 7 commits September 28, 2022 20:36

Add higher-level bindings

1c6130a

Rename sample project

c795dbf

Rename sample project

b4c9e37

Apply suggestions from code review

13a95a8

Co-authored-by: Günther Foidl <gue@korporal.at>

Update src/devices/Is31fl3730/Bonnet5x7x6.cs

bc4b4a4

Co-authored-by: Günther Foidl <gue@korporal.at>

Use lists/arrays more

565fa6e

Add MicrDotpHat binding

cd0dbc3

Ellerbach reviewed Oct 4, 2022

View reviewed changes

richlander and others added 13 commits October 4, 2022 20:26

Cleanup

e920490

Update per feedback

3e81307

Merge branch 'main' into Is31fl3730

f7524ad

Add Index/Range support for netstandard2.0

d82f7ff

Enable decimal point

8f7d961

Update target matrix

5b8c341

Add support for Micro Dot pHat

0d1e95f

Add Length concept

5923b31

Update ordering of matrices

a900e7c

Update README

a3800da

Change comment

bcd92dc

Merge branch 'main' into Is31fl3730

5712706

Switch to Slice syntax

ac4d819

richlander marked this pull request as ready for review December 18, 2022 17:48

Remove magic numbers

230a212

joperezr assigned pgrawehr Jan 5, 2023

pgrawehr requested changes Jan 6, 2023

View reviewed changes

ghost added the Needs: Author Feedback We are waiting for author to react to feedback (action required) label Jan 6, 2023

pgrawehr assigned richlander and unassigned pgrawehr Jan 6, 2023

Ellerbach reviewed Jan 6, 2023

View reviewed changes

Add solution file

5fad1d5

ghost removed the Needs: Author Feedback We are waiting for author to react to feedback (action required) label Jan 12, 2023

richlander and others added 7 commits January 16, 2023 14:11

Update src/devices/Is31fl3730/Current.cs

ecab9e3

Co-authored-by: Laurent Ellerbach <laurelle@microsoft.com>

Update per feedback

bf10f22

Update to PinValue

9396154

Update per feedback

de781f6

Update per feedback

0001fab

Remove IMatrix interface

d0d0964

Update type names

0921724

Ellerbach reviewed Jan 17, 2023

View reviewed changes

src/devices/Is31fl3730/FunctionRegister.cs Outdated Show resolved Hide resolved

richlander added 2 commits January 25, 2023 20:53

Update per feedback

2a81f18

Fix fill logic

a4222e8

Ellerbach approved these changes Feb 2, 2023

View reviewed changes

pgrawehr approved these changes Feb 2, 2023

View reviewed changes

Update per feedback

67ca483

pgrawehr merged commit 58c8b14 into dotnet:main Feb 12, 2023

richlander deleted the Is31fl3730 branch February 13, 2023 02:13

github-actions bot locked and limited conversation to collaborators Dec 8, 2023

	_i2cDevice.Write(new byte[] { LIGHTING_EFFECT_REGISTER, (byte)CurrentSetting });
	_i2cDevice.Write(stackalloc byte[] { LIGHTING_EFFECT_REGISTER, (byte)CurrentSetting });

	_i2cDevice.Write(new byte[] { address, value });
	_i2cDevice.Write(stackalloc byte[] { address, value });

Add binding for IS31FL3730 LED driver #1930

Add binding for IS31FL3730 LED driver #1930

Conversation

richlander commented Sep 22, 2022 • edited

Microsoft Reviewers: Open in CodeFlow

gfoidl left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

krwq Oct 5, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Ellerbach left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

richlander Nov 30, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pgrawehr commented Dec 25, 2022

richlander commented Jan 3, 2023

pgrawehr left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Ellerbach left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

richlander commented Jan 17, 2023

Ellerbach left a comment

Choose a reason for hiding this comment

richlander commented Feb 2, 2023

pgrawehr commented Feb 2, 2023

azure-pipelines bot commented Feb 2, 2023

pgrawehr left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

richlander commented Sep 22, 2022 •

edited

krwq Oct 5, 2022 •

edited

richlander Nov 30, 2022 •

edited