Proposed change to LCD part of Mainboard API


This is an open discussion on proposed API changes in GadgeteerCore's Mainboard API. This discussion is targeted at mainboard and LCD display vendors since it affects the mainboard and LCD display drivers. The proposed change would happen on transition to NETMF 4.2. GadgeteerCore for NETMF 4.1 will continue to use the existing API to ensure compatibility.
Status quo:
GadgeteerCore DisplayModule.cs currently takes care of rebooting the device when a display change occurs, such reboots are necessary to ensure that the LCD controller is properly configured. The reboots are done whenever the LCD controller enabled/disabled status changes, or whenever the SystemMetrics height/width does not match the LCD configuration height/width desired (and either and LCD or WPF is used).
1) LCD rotation is not supported
2) Checking height/width alone is not good enough - the whole set of Mainboard.LCDConfiguration values should be checked
3) The current code is too conservative and reboots when reboots are not required, e.g. when the LCD controller is not used by a program, but the LCD sockets (R,G,B) are not reused for any other purpose - disabling the LCD controller is not necessary (it does not affect the user program if it is left enabled, and is just annoying)
4) GadgeteerCore does not necessarily know when a reboot is required as this is mainboard specific. E.g. on Fez Spider, LCD rotation does not need a reboot but on Nano, it does.
5) The Mainboard.LCDConfiguration class is oriented towards supporting the LCD controller on the first available mainboard, the Fez Spider, but it may be missing one or more settings necessary for other LCD controllers.
Solutions proposed:
In each Mainboard's driver class, the implementation of
public abstract void SetLCD(LCDConfiguration lcdConfig);
should reboot the mainboard IF NECESSARY (i.e. if any of the settings change in a way that requires a reboot to take effect).
Also this will be renamed to
public abstract void SetLCDConfiguration(LCDConfiguration lcdConfig);
to disambiguate with SetLCDRotation (below).
In the Gadgeteer.Mainboard API, to add a call
abstract bool SetLCDRotation(GTM.Module.DisplayModule.LCDRotation rotation)
(where the LCDRotation enumeration specifies the four possible rotations, Normal, Clockwise90Degrees, UpsideDown, Counterclockwise90Degrees):
return value: true if the rotation is supported, false otherwise.
Note that this call will NOT be at constructor time (which is when SetLCDConfiguration is called) - it will be later. This is because we cannot pass parameters (other than the socket number(s)) to constructors using the designer. We will add a method in DisplayModule.cs that end users can use, e.g. in ProgramStarted, which will pass the setting down to the mainboard driver and debug print an error message if the rotation is not supported. This will also check if WPFWindow has been used already, and debug print an error message if so (rotation must be called first before WPF is used since otherwise the systemmetrics width/height and hence the window size are wrong).
public virtual void SetRotation(LCDRotation rotation)
The mainboard driver is also responsible for rebooting if necessary during this call (as for the above call).
DisplayModule.cs in GadgeteerCore will be modified to ONLY call Mainboard.SetLCDConfiguration if the new display configuration is absolutely needed. E.g. if the user program instantiates an LCD-based display module, or uses WPF on any display, or reuses an LCD controller pin as a GPIO (which requires the LCD controller to be disabled). However, if the user does not use an LCD, WPF or use the LCD controller sockets, then Mainboard.SetLCD will NOT BE CALLED - this means that the LCD controller will remain configured in its old state, but since the user is not using it, that's fine.
In the Mainboard.LCDConfiguration class, we might want to add new settings to cope with features available on other LCD controllers. Note that each settings should have a good "default" in case an LCD controller is not capable of using it. Please propose settings if you see a need to support current/future LCD controllers.
It is important that we get this (and any other GadgeteerCore API changes) right before a GadgeteerCore release for NETMF 4.2 is finalised, since we are very averse to API changes (other than additions if really necessary) since they would break compatibility with any programs/module/mainboard drivers.


jamesscott wrote May 11, 2012 at 9:25 AM

The changes described above are present in the release 2.42.600.

wrote Feb 22, 2013 at 12:45 AM

wrote May 16, 2013 at 12:26 PM

wrote May 16, 2013 at 12:26 PM

wrote Jun 14, 2013 at 8:28 AM