Merge pull request #3 from mrmcwethy/prepforbundle

brentru · web-flow · commit e1a939ad4879 · 2017-11-29T21:47:12.000-05:00
Attempt to update readme documents.
diff --git a/README.md b/README.md
@@ -2,15 +2,18 @@
 Introduction
 ============
 
-This repo is compatible with standard Character LCDs.
+This library is compatible with standard Character LCDs such as:
+* [Adafruit Standard LCD 16x2](https://www.adafruit.com/product/181)
+* [Adafruit RGB backlight negative LCD 16x2](https://www.adafruit.com/product/399)
+* [Adafruit RGB backlight negative LCD 20x4](https://www.adafruit.com/product/498)
 
-Compatible with CircuitPython Versions: 1.0.0 
+Compatible with CircuitPython Versions: 2.x
 
 Dependencies
 =============
 This driver depends on:
 
-* [Adafruit CircuitPython](https://github.com/adafruit/circuitpython "cirpyth repo")
+* [Adafruit CircuitPython](https://github.com/adafruit/circuitpython "CircuitPython")
 
 
 Please ensure all dependencies are available on the CircuitPython filesystem.
@@ -20,11 +23,11 @@ This is easily achieved by downloading
 Usage Example
 =============
 
-The ``LCD`` class interfaces a predefined Character LCD display with CircuitPython.
+The ``Character_LCD`` class interfaces a predefined Character LCD display with CircuitPython.
 
-    import adafruit_character_lcd as LCD
+    import adafruit_character_lcd
 
-You must define the data pins (``RS``, ``EN``, ``D4``, ``D5``, ``D6``, ``D7``) in your code before using the ``LCD`` class. 
+You must define the data pins (``RS``, ``EN``, ``D4``, ``D5``, ``D6``, ``D7``) in your code before using the ``Character_LCD`` class.
 If you want to have on/off ``backlight`` functionality, you can also define your backlight as ``lcd_backlight``. Otherwise, the backlight will always remain on. An example of this is below
 
     lcd_rs = digitalio.DigitalInOut(D7)
@@ -38,24 +41,41 @@ If you want to have on/off ``backlight`` functionality, you can also define your
 You must also define the size of the CharLCD by specifying its ``lcd_columns`` and ``lcd_rows``:
 
     lcd_columns = 16
-    lcd_rows = 2 
+    lcd_rows = 2
 
-After you have set up your LCD, we can make the device by calling it 
+After you have set up your LCD, we can make the device by calling it
 
-    lcd = LCD.cirpyth_char_lcd(lcd_rs, lcd_en, lcd_d4, lcd_d5, lcd_d6, lcd_d7, lcd_columns, lcd_rows, lcd_backlight)
+    lcd = adafruit_character_lcd.Character_LCD(lcd_rs, lcd_en, lcd_d4, lcd_d5, lcd_d6, lcd_d7, lcd_columns, lcd_rows, lcd_backlight)
 
 
 To verify that your pins are correct, print a hello message to the CharLCD:
 
     lcd.message('hello\ncircuitpython')
 
 
-Custom character example with create_char() is provided within /examples/ 
-    
+Custom character example with create_char() is provided within /examples/
 
 
 Contributing
 ============
 
 Contributions are welcome! Please read our [Code of Conduct](https://github.com/adafruit/Adafruit_CircuitPython_CircuitPython_CharLCD/blob/master/CODE_OF_CONDUCT.md)
 before contributing to help this project stay welcoming.
+
+Installation
+============
+
+This library is **NOT** built into CircuitPython to make it easy to update. To
+install it either follow the directions below or :ref:`install the library bundle <bundle_installation>`.
+
+To install:
+
+#. Download and unzip the `latest release zip <https://github.com/adafruit/Adafruit_CircuitPython_CharLCD/releases>`_.
+#. Copy the unzipped ``adafruit_character_lcd`` to the ``lib`` directory on the ``CIRCUITPY`` or ``MICROPYTHON`` drive.
+
+API
+===
+.. toctree::
+    :maxdepth: 3
+
+    api
diff --git a/adafruit_character_lcd/character_lcd.py b/adafruit_character_lcd/character_lcd.py
@@ -23,7 +23,6 @@
 `adafruit_CircuitPython_CharLCD`
 ====================================================
 
-TODO(description)
 
 * Author(s):
 -Brent Rubell
@@ -32,7 +31,7 @@
 """
 
 """
-`adafruit_character_lcd` - character lcd module
+:mod:`adafruit_character_lcd`
 =================================================
 module for interfacing with character lcds
 """
@@ -84,19 +83,21 @@
 
 class Character_LCD(object):
     """ Interfaces with a character LCD
-          :param rs: The reset data line
-          :param en: The enable data line
-          :param d4, d5, d6, d7: The data lines 4 thru 7
+          :param ~digitalio.DigitalInOut rs: The reset data line
+          :param ~digitalio.DigitalInOut en: The enable data line
+          :param ~digitalio.DigitalInOut d4: The data line 4
+          :param ~digitalio.DigitalInOut d5: The data line 5
+          :param ~digitalio.DigitalInOut d6: The data line 6
+          :param ~digitalio.DigitalInOut d7: The data line 7
           :param cols: The columns on the charLCD
           :param lines: The lines on the charLCD
-          :param backlight: The backlight pin, usually the last pin. Check with your datasheet
-          :param enable_pwm: The PWM CONTROL, TODO
-          :param initial_backlight: THE initial backlight status (on/off)
+          :param ~digitalio.DigitalInOut backlight: The backlight pin, usually the last pin. Check with your datasheet
       """
     def __init__(self, rs, en, d4, d5, d6, d7, cols, lines,
-          backlight = None,
-          enable_pwm = False,
-          initial_backlight = 1.0):
+          backlight = None #,
+          #enable_pwm = False,
+          #initial_backlight = 1.0
+          ):
 
       self.cols = cols
       self.lines = lines
@@ -109,9 +110,7 @@ def __init__(self, rs, en, d4, d5, d6, d7, cols, lines,
       self.d7 = d7
       # backlight pin
       self.backlight = backlight
-      # save backlight state
-      self.backlight = backlight
-      self.pwn_enabled = enable_pwm
+      # self.pwn_enabled = enable_pwm
       # set all pins as outputs
       for pin in(rs, en, d4, d5, d6, d7):
         pin.direction = digitalio.Direction.OUTPUT
@@ -147,7 +146,9 @@ def clear(self):
       time.sleep(0.003)
 
     def show_cursor(self, show):
-      """Show or hide the cursor"""
+      """Show or hide the cursor
+            :param show: True to show cursor, False to hide
+      """
       if show:
         self.displaycontrol |= LCD_CURSORON
       else:
@@ -166,7 +167,9 @@ def set_cursor(self, col, row):
       self._write8(LCD_SETDDRAMADDR | (col + LCD_ROW_OFFSETS[row]))
 
     def blink(self, blink):
-      """Blinks the cursor if blink = true."""
+      """Blinks the cursor if blink = true.
+            :param blink: True to blink, False no blink
+      """
       if blink == True:
         self.displaycontrol |= LCD_BLINKON
       else:
@@ -192,7 +195,9 @@ def set_right_to_left(self):
       self._write8(LCD_ENTRYMODESET | self.displaymode)
 
     def enable_display(self, enable):
-        """Enable or disable the display.  Set enable to True to enable."""
+        """Enable or disable the display.
+            :param enable: True to enable display, False to disable
+        """
         if enable:
           self.displaycontrol |= LCD_DISPLAYON
         else:
@@ -234,15 +239,19 @@ def _pulse_enable(self):
       time.sleep(0.0000001)
 
     def set_backlight(self, lighton):
-      """ Set lighton to turn the charLCD backlight on. """
+      """ Set lighton to turn the charLCD backlight on.
+            :param lighton: True to turn backlight on, False to turn off
+      """
       if lighton:
         self.backlight.value = 0
       else:
         self.backlight.value = 1
 
 
     def message(self, text):
-      """Write text to display, can include \n for newline"""
+      """Write text to display, can include \n for newline
+            :param text: string to display
+      """
       line = 0
       #  iterate thru each char
       for char in text:
@@ -262,6 +271,9 @@ def create_char(self, location, pattern):
         provide an array of 8 bytes containing the pattern. E.g. you can easyly
         design your custom character at http://www.quinapalus.com/hd44780udg.html
         To show your custom character use eg. lcd.message('\x01')
+            :param location: integer in range(8) to store the created character
+            :param ~bytes pattern: len(8) describes created character
+
         """
         # only position 0..7 are allowed
         location &= 0x7
diff --git a/adafruit_character_lcd/character_lcd_RGB.py b/adafruit_character_lcd/character_lcd_RGB.py
@@ -23,7 +23,6 @@
 `adafruit_CircuitPython_CharLCD`
 ====================================================
 
-TODO(description)
 
 * Author(s):
 -Brent Rubell
@@ -32,7 +31,7 @@
 """
 
 """
-`adafruit_character_lcd_RGB` - RGB character lcd module
+:mod:`adafruit_character_lcd_RGB`
 =================================================
 module for interfacing with RGB character lcds
 """
@@ -86,25 +85,29 @@
 
 class Character_LCD_RGB(object):
     """ Interfaces with a character LCD
-          :param ~microcontroller.Pin rs: The reset data line
-          :param ~microcontroller.Pin en: The enable data line
-          :param ~microcontroller.Pin d4, d5, d6, d7: The data lines 4 thru 7
-          :param ~microcontroller.Pin cols: The columns on the charLCD
-          :param ~microcontroller.Pin lines: The lines on the charLCD
-          :param ~microcontroller.Pin red: Red RGB Anode
-          :param ~microcontroller.Pin green: Green RGB Anode
-          :param ~microcontroller.Pin blue: Blue RGB Anode
-          :param ~microcontroller.Pin backlight: The backlight pin, usually the last pin. Consult the datasheet.
-          :param enable_pwm: PulseIO Control
-          :param initial_backlight: THE initial backlight status (on/off)
+        :param ~digitalio.DigitalInOut rs: The reset data line
+        :param ~digitalio.DigitalInOut en: The enable data line
+        :param ~digitalio.DigitalInOut d4: The data line 4
+        :param ~digitalio.DigitalInOut d5: The data line 5
+        :param ~digitalio.DigitalInOut d6: The data line 6
+        :param ~digitalio.DigitalInOut d7: The data line 7
+        :param cols: The columns on the charLCD
+        :param lines: The lines on the charLCD
+        :param ~pulseio.PWMOut red: Red RGB Anode
+        :param ~pulseio.PWMOut green: Green RGB Anode
+        :param ~pulseio.PWMOut blue: Blue RGB Anode
+        :param ~digitalio.DigitalInOut backlight: The backlight pin, usually the last pin. Consult the datasheet.
+            Note that Pin value 0 means blaklight is lit.
+
       """
     def __init__(self, rs, en, d4, d5, d6, d7, cols, lines,
           red,
           green,
           blue,
-          backlight = None,
-          enable_pwm = False,
-          initial_backlight = 1.0):
+          backlight = None #,
+          #enable_pwm = False,
+          #initial_backlight = 1.0
+          ):
       #  define columns and lines
       self.cols = cols
       self.lines = lines
@@ -123,9 +126,7 @@ def __init__(self, rs, en, d4, d5, d6, d7, cols, lines,
       self.RGBLED = [red, green, blue]
       # define backlight pin
       self.backlight = backlight
-      # save backlight state
-      self.backlight = backlight
-      self.pwn_enabled = enable_pwm
+      # self.pwn_enabled = enable_pwm
       # set all pins as outputs
       for pin in(rs, en, d4, d5, d6, d7):
         pin.direction = digitalio.Direction.OUTPUT
@@ -180,7 +181,9 @@ def set_cursor(self, col, row):
       self._write8(_LCD_SETDDRAMADDR | (col + LCD_ROW_OFFSETS[row]))
 
     def enable_display(self, enable):
-        """Enable or disable the display.  Set enable to True to enable."""
+        """Enable or disable the display.
+            :param enable: True to enable display, False to disable
+        """
         if enable:
           self.displaycontrol |= _LCD_DISPLAYON
         else:
@@ -222,7 +225,9 @@ def _pulse_enable(self):
       time.sleep(0.0000001)
 
     def set_backlight(self, lighton):
-      """ Set lighton to turn the charLCD backlight on. """
+      """ Set lighton to turn the charLCD backlight on.
+            :param lighton: True to turn backlight on, False to turn off
+      """
       if lighton:
         self.backlight.value = 0
       else:
@@ -239,13 +244,17 @@ def _map(self, x, in_min, in_max, out_min, out_max):
             return max(min(ret, out_min), out_max)
 
     def setColor(self, color):
-        """ Method to set the duty cycle of the RGB LED """
+        """ Method to set the duty cycle of the RGB LED
+            :param color: list of 3 integers in range(100). ``[R,G,B]`` 0 is no color, 100 it maximum color
+        """
         self.RGBLED[0].duty_cycle = int(self._map(color[0], 0, 100, 65535, 0))
         self.RGBLED[1].duty_cycle = int(self._map(color[1], 0, 100, 65535, 0))
         self.RGBLED[2].duty_cycle = int(self._map(color[2], 0, 100, 65535, 0))
 
     def message(self, text):
-      """Write text to display, can include \n for newline"""
+      """Write text to display, can include \n for newline
+            :param text: string to display
+      """
       line = 0
       #  iterate thru each char
       for char in text:
diff --git a/api.rst b/api.rst
@@ -1,5 +1,12 @@
 
-.. If you created a package, create one automodule per module in the package.
+`Character_LCD` - for interfacing with character lcds
++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
-.. automodule:: adafruit_circuitpython_charlcd
+.. automodule:: adafruit_character_lcd.character_lcd
    :members:
+
+`Character_LCD_RGB` - for interfacing with RGB character lcds
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. automodule:: adafruit_character_lcd.character_lcd_RGB
+    :members:
diff --git a/examples/rgb_hello_CircuitPython.py b/examples/rgb_hello_CircuitPython.py
