Diff: RA8875.h

Revision:

182:8832d03a2a29

Parent:

181:0032d1b8f5d4

Child:

185:cb7591a43f44

--- a/RA8875.h	Fri Aug 02 02:12:26 2019 +0000
+++ b/RA8875.h	Sat Aug 03 00:26:33 2019 +0000
@@ -4,6 +4,8 @@
 /// The RA8875 Display controller is a powerful interface for low cost displays. It
 /// can support displays up to 800 x 480 pixels x 16-bit color. 
 ///
+/// @image html Example_Program.png "Image of an Example Program"
+///
 /// Aside from 800 x 480 pixel displays, another common implementation is 
 /// 480 x 272 x 16 with two layers. The two layers can be exchanged, or blended 
 /// in various ways (transparency, OR, AND, and more). It includes graphics 
@@ -53,6 +55,7 @@
 /// * @ref Hardwired_KeyPad
 /// * @ref Example_Program
 /// * @ref Wiring_Diagram
+/// * @ref External_Resources
 /// * @ref Future_Plans
 ///
 /// @todo Add APIs for the 2nd RA8875 PWM channel. If the frequency can be independently
@@ -92,6 +95,8 @@
 /// the display is instantiated, after which nearly any of the available commands
 /// may be issued.
 ///
+/// @image html RA8875_Display.png "Schematic Representation of the Display"
+///
 /// During the instantiation, the display is powered on, cleared, and the backlight
 /// is energized. Additionally, the keypad and touchscreen features are activated.
 /// It is important to keep in mind that the keypad has its default mapping, 
@@ -127,11 +132,23 @@
 /// There is support for various touch panel interfaces.
 /// * @ref Resistive_Touch_Panel - native control for a resistive touch panel. 
 ///     There are a few steps to enable this interface.
+///
+/// For the Capacitive Touch controllers, an I2C interface is required.
+///
+/// @image html RA8875_Touch.png "Schematic Representation of the Touch Interface"
+///
 /// * @ref CapSense_FT5206 - FT5206 capacitive touch controller, integrated in 
 ///     several popular RA8875-based displays. See @ref Capacitive_Touch_Panel.
 /// * @ref CapSense_GSL1680 - GSL1680 capacitive touch controller, integrated in 
 ///     several popular RA8875-based displays. See @ref Capacitive_Touch_Panel.
 ///
+/// @page MicroSD_Interface Micro SD Interface
+///
+/// Several of the displays from BuyDisplay.com include the option for a Micro SD
+/// card adapter. This is not tied in to the RA8875 controller, it is just provided
+/// as a convenience to the display product.
+///
+/// @image html RA8875_MicroSD.png "Schematic Representation of the Micro SD Interface"
 ///
 ///
 /// @page Hardwired_KeyPad Hardwired Keypad
@@ -141,6 +158,8 @@
 /// could be a set of independent functions, or they could be wired as a simple 
 /// calculator or telephone style of keypad.
 ///
+/// @image html RA8875_Keypad.png "Schematic Representation of the Keypad Interface"
+///
 /// Various parameters can be configured, such as the scan rate, using @ref RA8875::KeypadInit().
 /// The keypad has a default keypad mapping, but there is an API that permits
 /// installing a custom @ref RA8875::SetKeyMap().
@@ -184,6 +203,8 @@
 /// This is the less common controller. It supports either 5 or 10 simultaneous touch point
 /// tracking, depending on the firmware installed in the controller.
 ///
+
+
 /// @page Example_Program Example Program
 ///
 /// This is just a small sample of what can be done, and what it can look like:
@@ -215,6 +236,8 @@
 /// }
 /// @endcode
 ///
+
+
 /// @page Wiring_Diagram Example Wiring Diagram
 ///
 /// This library was crafted around the 4-Wire SPI interface. This was the chosen 
@@ -222,8 +245,59 @@
 /// the capability of this display. Alternatives include: 3-Wire SPI, I2C, 8-bit and
 /// 16-bit parallel.
 /// 
-/// @image html Example_Wiring.png "Example Wiring Diagram"
+/// @section Schematic_Basic Basic Schematic 
+///
+/// The basic schematic should be the most portable to any system that has SPI support.
+/// 
+/// @image html RA8875_display_schematic.png "Basic Display support"
+///
+/// @section Schematic_DisplayTouch Display with Capacitive Touch
+///
+/// A more advanced schematic - this with the I2C interface connecting to the Capacitive
+/// Touch controller. Note that this requires additional IO pins.
+///
+/// @image html RA8875_captouch_wiring.png "Display and Capacitive Touch support"
+///
+/// @section Schematic_DisplayTouchMicroSD Display with Capacitive Touch and micro SD
+///
+/// The most advanced schematic - taking advantage of the display, the capacitive touch 
+/// controller, and the peripheral support for a micro SD card on some of the display 
+/// modules.
+///
+/// @note There are online indications that the RA8875 has a defect in its SPI interface
+///         where it will not release the MISO pin. If this pin is shared with the micro SD
+///         port, then it could interfere with successful read/write of the files.  
+///         The easiest solution is to put that interface on a separate SPI port.
+///
+/// @image html RA8875_display_full.png "Display, Touch, and micro SD support"
 ///
+/// @page External_Resources External Resources
+///
+/// There are many websites with information on the RA8875 Display. This partial list 
+/// may be helpful:
+///
+/// * <a href="https://os.mbed.com/components/RA8875-Based-Display/">RA8875 Library</a> 
+///     on the <a href="https://os.mbed.com/">mbed site</a><br/>
+///     This page has **a lot** of detail, schematices, sample programs, instructions to
+///     create your own fonts, and more...
+/// * <a href="https://os.mbed.com/search/?q=RA8875">RA8875 search on the mbed site</a><br/>
+///     Many more links, discussions, questions and answers, and more...
+/// * <a href="https://www.buydisplay.com/">Buy Display</a> site<br/>
+///     Where you can find many inexpensive displays, some with the **RA8875** controller
+///     (which this library supports), and others using different controllers (thus not
+///     supported by this library).
+/// * <a href="https://github.com/sumotoy/RA8875/wiki/Fix-compatibility-with-other-SPI-devices">SPI Bug notes</a><br/>
+///     A link to a site that discusses a SPI bug on the RA8875. [I have not verified this
+///     bug]
+/// * <a href="https://www.google.com/search?safe=on&source=hp&ei=1oN1XP6hEsPq_AbZlKMw&q=RA8875">RA8875 - Google</a><br/>
+///     Because new things show up all the time.
+/// * <a href="https://www.bing.com/search?q=RA8875">RA8875 - Bing</a><br/>
+///     And you want to look in more than one place.
+///
+/// @image html RA8875_display_full.png "Example Wiring Diagram"
+///
+
+
 /// @page Future_Plans Future Plans
 ///
 /// Following are some notions of future plans. This does not mean they will all be
@@ -266,6 +340,18 @@
 ///     PrintScreen method with either an internal helper (for file system access) or
 ///     a callback for the user handled process.
 ///
+/// - Add support for the hardware reset pin
+///
+/// - Figure out how to "init()" in the constructor when it is not in main(). I ran into 
+///        some issues if the display was instantiated before main(), and the code would not 
+///        run, thus the exposure and activation of the init() function. If the instantiation 
+///        is within main(), then it seemed to work as expected. 
+///
+/// - Add Scroll support for text. 
+///
+/// - Add high level objects - x-y graph, meter, buttons, ... but these will probably be 
+///        best served in another class, since they may not be needed for many uses.
+///
 #ifndef RA8875_H
 #define RA8875_H
 #include <mbed.h>
@@ -1314,7 +1400,7 @@
     /// Initialize the keypad interface on the RA8875 controller.
     ///
     /// Enables the keypad subsystem. It will scan the 4 x 5 matrix
-    /// and make available key presses.
+    /// and make available key presses. See also @ref SetKeyMap().
     ///
     /// @note See section 5-13 of RAIO RA8875 data sheet for more details.
     /// @note When using the display from buy-display.com, be sure that
@@ -1340,6 +1426,7 @@
     /// Create Key Code definitions for the key matrix.
     ///
     /// This API provides a table of 22 key-code assignments for the matrix of keys.
+    /// See also KeypadInit().
     /// This can be used to translate the keys 1 - 20 into some other value, as
     /// well as to communicate the "no key" (zero) and "error state" (21).
     ///
@@ -3048,6 +3135,8 @@
 
 
 private:
+    void InitAllMemberVars();
+
     /// Touch panel parameters - common to both resistive and capacitive
     
     /// Data type to indicate which TP, if any, is in use.
@@ -3069,9 +3158,7 @@
     ////////////////// Start of Capacitive Touch Panel parameters
     
     int RoundUp(int value, int roundTo);
-public:
     uint8_t FT5206_TouchPositions(void);
-private:
     uint8_t FT5206_ReadRegU8(uint8_t reg);
     uint8_t GSL1680_TouchPositions(void);
     uint8_t GSL1680_ReadRegU8(uint8_t reg, uint8_t * buf, int count);
@@ -3315,7 +3402,7 @@
         PRF_DRAWCIRCLE,
         PRF_DRAWELLIPSE,
         PRF_BLOCKMOVE,
-        METRICCOUNT
+        METRICCOUNT = PRF_BLOCKMOVE
     } method_e;
     unsigned long metrics[METRICCOUNT];
     unsigned long idletime_usec;