From fe4c7b15836691a2dc83c0608871ca26d68faf92 Mon Sep 17 00:00:00 2001 From: Jeff Epler Date: Sat, 28 Dec 2019 21:05:59 -0600 Subject: [PATCH 1/3] Improve documentation --- adafruit_seesaw/analoginput.py | 14 +++++++++++ adafruit_seesaw/crickit.py | 10 +++++++- adafruit_seesaw/digitalio.py | 20 ++++++++++++++++ adafruit_seesaw/keypad.py | 35 ++++++++++++++++++++++++++- adafruit_seesaw/neopixel.py | 23 +++++++++++++++++- adafruit_seesaw/pwmout.py | 7 +++++- adafruit_seesaw/robohat.py | 18 +++++++++++++- adafruit_seesaw/samd09.py | 19 ++++++++++++++- adafruit_seesaw/seesaw.py | 43 ++++++++++++++++++++++++++++++---- adafruit_seesaw/tftshield18.py | 33 +++++++++++++++++++------- docs/api.rst | 34 +++++++++++++++++++++++++++ docs/conf.py | 9 ++++++- 12 files changed, 244 insertions(+), 21 deletions(-) diff --git a/adafruit_seesaw/analoginput.py b/adafruit_seesaw/analoginput.py index 548eadd..55acb72 100644 --- a/adafruit_seesaw/analoginput.py +++ b/adafruit_seesaw/analoginput.py @@ -21,10 +21,22 @@ # THE SOFTWARE. # pylint: disable=missing-docstring,invalid-name,too-many-public-methods +""" +`adafruit_seesaw.analoginput` +==================================================== +""" + __version__ = "0.0.0-auto.0" __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_seesaw.git" class AnalogInput: + """CircuitPython-compatible class for analog inputs + + This class is intended to be a compatible subset of `analogio.AnalogIn` + + :param ~adafruit_seesaw.seesaw.Seesaw seesaw: The device + :param int pin: The pin number on the device +""" def __init__(self, seesaw, pin): self._seesaw = seesaw self._pin = pin @@ -34,8 +46,10 @@ def deinit(self): @property def value(self): + """The current analog value on the pin, as an integer from 0..65535 (inclusive)""" return self._seesaw.analog_read(self._pin) @property def reference_voltage(self): + """The reference voltage for the pin""" return 3.3 diff --git a/adafruit_seesaw/crickit.py b/adafruit_seesaw/crickit.py index 0e52d41..6f415e5 100644 --- a/adafruit_seesaw/crickit.py +++ b/adafruit_seesaw/crickit.py @@ -21,7 +21,15 @@ # THE SOFTWARE. # pylint: disable=missing-docstring,invalid-name,too-many-public-methods,too-few-public-methods -from micropython import const +""" +`adafruit_seesaw.crickit` - Pin definition for Adafruit CRICKIT +=============================================================== +""" + +try: + from micropython import const +except ImportError: + def const(x): return x __version__ = "0.0.0-auto.0" __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_seesaw.git" diff --git a/adafruit_seesaw/digitalio.py b/adafruit_seesaw/digitalio.py index 45ccd4c..7e77819 100644 --- a/adafruit_seesaw/digitalio.py +++ b/adafruit_seesaw/digitalio.py @@ -21,12 +21,26 @@ # THE SOFTWARE. # pylint: disable=missing-docstring,invalid-name,too-many-public-methods +""" +`adafruit_seesaw.digitalio` +==================================================== +""" + import digitalio __version__ = "0.0.0-auto.0" __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_seesaw.git" class DigitalIO: + """CircuitPython-compatible class for digital I/O pins + + This class is intended to be a compatible subset of `digitalio.DigitalInOut`. + + Due to technical limitations, PULL_DOWNs are not supported. + + :param ~adafruit_seesaw.seesaw.Seesaw seesaw: The device + :param int pin: The pin number on the device +""" def __init__(self, seesaw, pin): self._seesaw = seesaw self._pin = pin @@ -39,12 +53,14 @@ def deinit(self): pass def switch_to_output(self, value=False, drive_mode=digitalio.DriveMode.PUSH_PULL): + """Switch the pin to output mode""" self._seesaw.pin_mode(self._pin, self._seesaw.OUTPUT) self._seesaw.digital_write(self._pin, value) self._drive_mode = drive_mode self._pull = None def switch_to_input(self, pull=None): + """Switch the pin to input mode""" if pull == digitalio.Pull.DOWN: raise ValueError("Pull Down currently not supported") elif pull == digitalio.Pull.UP: @@ -55,6 +71,7 @@ def switch_to_input(self, pull=None): @property def direction(self): + """Retrieve or set the direction of the pin""" return self._direction @direction.setter @@ -69,6 +86,7 @@ def direction(self, value): @property def value(self): + """Retrieve or set the value of the pin""" if self._direction == digitalio.Direction.OUTPUT: return self._value return self._seesaw.digital_read(self._pin) @@ -82,6 +100,7 @@ def value(self, val): @property def drive_mode(self): + """Retrieve or set the drive mode of an output pin""" return self._drive_mode @drive_mode.setter @@ -90,6 +109,7 @@ def drive_mode(self, mode): @property def pull(self): + """Retrieve or set the pull mode of an input pin""" return self._pull @pull.setter diff --git a/adafruit_seesaw/keypad.py b/adafruit_seesaw/keypad.py index 414708b..c05bb10 100644 --- a/adafruit_seesaw/keypad.py +++ b/adafruit_seesaw/keypad.py @@ -21,7 +21,15 @@ # THE SOFTWARE. # pylint: disable=missing-docstring,invalid-name,too-many-public-methods -from micropython import const +""" +`adafruit_seesaw.keypad` +==================================================== +""" + +try: + from micropython import const +except ImportError: + def const(x): return x from adafruit_seesaw.seesaw import Seesaw __version__ = "0.0.0-auto.0" @@ -38,16 +46,30 @@ # pylint: disable=too-few-public-methods class KeyEvent: + """Holds information about a key event in its properties + + :param int num: The number of the key + :param int edge: One of the EDGE propertes of `adafruit_seesaw.keypad.Keypad` + """ def __init__(self, num, edge): self.number = int(num) self.edge = int(edge) # pylint: enable=too-few-public-methods class Keypad(Seesaw): + """On compatible SeeSaw devices, reads from a keypad. + + :param ~busio.I2C i2c_bus: Bus the SeeSaw is connected to + :param int addr: I2C address of the SeeSaw device + :param ~digitalio.DigitalInOut drdy: Pin connected to SeeSaw's 'ready' output""" + """Indicates that the key is currently pressed""" EDGE_HIGH = 0 + """Indicates that the key is currently released""" EDGE_LOW = 1 + """Indicates that the key was recently pressed""" EDGE_FALLING = 2 + """Indicates that the key was recently released""" EDGE_RISING = 3 def __init__(self, i2c_bus, addr=0x49, drdy=None): @@ -56,6 +78,7 @@ def __init__(self, i2c_bus, addr=0x49, drdy=None): @property def interrupt_enabled(self): + """Retrieve or set the interrupt enable flag""" return self._interrupt_enabled @interrupt_enabled.setter @@ -71,6 +94,7 @@ def interrupt_enabled(self, value): @property def count(self): + """Retrieve or set the number of keys""" return self.read8(_KEYPAD_BASE, _KEYPAD_COUNT) # pylint: disable=unused-argument, no-self-use @@ -80,6 +104,12 @@ def count(self, value): # pylint: enable=unused-argument, no-self-use def set_event(self, key, edge, enable): + """Control which kinds of events are set + + :param int key: The key number + :param int edge: The type of event + :param bool enable: True to enable the event, False to disable it""" + if enable not in (True, False): raise ValueError("event enable must be True or False") if edge > 3 or edge < 0: @@ -92,6 +122,9 @@ def set_event(self, key, edge, enable): self.write(_KEYPAD_BASE, _KEYPAD_EVENT, cmd) def read_keypad(self, num): + """Read data from the keypad + + :param int num: The number of bytes to read""" ret = bytearray(num) self.read(_KEYPAD_BASE, _KEYPAD_FIFO, ret) return ret diff --git a/adafruit_seesaw/neopixel.py b/adafruit_seesaw/neopixel.py index a994901..35586f6 100644 --- a/adafruit_seesaw/neopixel.py +++ b/adafruit_seesaw/neopixel.py @@ -21,11 +21,19 @@ # THE SOFTWARE. # pylint: disable=missing-docstring,invalid-name,too-many-public-methods +""" +`adafruit_seesaw.neopixel` +==================================================== +""" + try: import struct except ImportError: import ustruct as struct -from micropython import const +try: + from micropython import const +except ImportError: + def const(x): return x __version__ = "1.2.3" __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_seesaw.git" @@ -50,6 +58,16 @@ """Green Red Blue White""" class NeoPixel: + """Control NeoPixels connected to a seesaw + + :param ~adafruit_seesaw.seesaw.Seesaw seesaw: The device + :param int pin: The pin number on the device + :param int n: The number of pixels + :param int bpp: The number of bytes per pixel + :param float brightness: The brightness, from 0.0 to 1.0 + :param bool auto_write: Automatically update the pixels when changed + :param tuple pixel_order: The layout of the pixels. Use one of the order constants such as RGBW. +""" def __init__(self, seesaw, pin, n, *, bpp=3, brightness=1.0, auto_write=True, pixel_order=None): # TODO: brightness not yet implemented. self._seesaw = seesaw @@ -84,6 +102,7 @@ def __len__(self): return self._n def __setitem__(self, key, color): + """Set one pixel to a new value""" cmd = bytearray(2 + self._bpp) struct.pack_into(">H", cmd, 0, key * self._bpp) if isinstance(color, int): @@ -127,6 +146,7 @@ def __getitem__(self, key): pass def fill(self, color): + """Set all pixels to the same value""" # Suppress auto_write while filling. current_auto_write = self.auto_write self.auto_write = False @@ -137,4 +157,5 @@ def fill(self, color): self.auto_write = current_auto_write def show(self): + """Update the pixels even if auto_write is False""" self._seesaw.write(_NEOPIXEL_BASE, _NEOPIXEL_SHOW) diff --git a/adafruit_seesaw/pwmout.py b/adafruit_seesaw/pwmout.py index 1ab5457..0eacf44 100644 --- a/adafruit_seesaw/pwmout.py +++ b/adafruit_seesaw/pwmout.py @@ -21,6 +21,11 @@ # THE SOFTWARE. # pylint: disable=missing-docstring,invalid-name,too-many-public-methods,too-few-public-methods +""" +`adafruit_seesaw.pwmout` +==================================================== +""" + __version__ = "0.0.0-auto.0" __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_seesaw.git" @@ -34,7 +39,7 @@ def __init__(self, seesaw, pin): @property def frequency(self): - """The overall PWM frequency in herz.""" + """The overall PWM frequency in Hertz.""" return self._frequency @frequency.setter diff --git a/adafruit_seesaw/robohat.py b/adafruit_seesaw/robohat.py index 6cf3cc3..12b9cbe 100644 --- a/adafruit_seesaw/robohat.py +++ b/adafruit_seesaw/robohat.py @@ -21,7 +21,15 @@ # THE SOFTWARE. # pylint: disable=missing-docstring,invalid-name,too-many-public-methods,too-few-public-methods -from micropython import const +""" +`adafruit_seesaw.robohat` - Pin definition for RoboHAT +====================================================== +""" + +try: + from micropython import const +except ImportError: + def const(x): return x __version__ = "0.0.0-auto.0" __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_seesaw.git" @@ -73,22 +81,30 @@ # PB pins are 32+nn class MM1_Pinmap: + """This class is automatically used by `adafruit_seesaw.seesaw.Seesaw` when + a RoboHAT board is detected. + + It is also a reference for the capabilities of each pin.""" # seesaw firmware (mm1_hat) analog pin map: # analog[0]:47 analog[1]:48 analog[2]: analog[3]: # analog[4]: analog[5]: analog[6]: analog[7]: # + """The pins capable of analog output""" analog_pins = (_MM1_D3, _MM1_D2) + """The effective bit resolution of the PWM pins""" pwm_width = 16 # seesaw firmware (mm1_hat) pwm pin map: # pwm[0]:16 pwm[1]:17 pwm[2]:18 pwm[3]:19 pwm[4]:11 pwm[5]:10 # pwm[6]:9 pwm[7]:8 pwm[8]:40 pwm[9]:41 pwm[10]:42 pwm[11]:43 # + """The pins capable of PWM output""" pwm_pins = (_MM1_SERVO1, _MM1_SERVO2, _MM1_SERVO3, _MM1_SERVO4, _MM1_SERVO5, _MM1_SERVO6, _MM1_SERVO7, _MM1_SERVO8, _MM1_D12, _MM1_D10, _MM1_D11, _MM1_D9) # seesaw firmware touch pin map: # touch[0]: 7 touch[1]: 6 touch[2]: 5 touch[3]: 4 + """The pins capable of touch input""" touch_pins = (_MM1_RCH1, _MM1_RCH2, _MM1_RCH3, _MM1_RCH4) diff --git a/adafruit_seesaw/samd09.py b/adafruit_seesaw/samd09.py index dd19627..a10c9b2 100644 --- a/adafruit_seesaw/samd09.py +++ b/adafruit_seesaw/samd09.py @@ -21,7 +21,15 @@ # THE SOFTWARE. # pylint: disable=missing-docstring,invalid-name,too-many-public-methods,too-few-public-methods -from micropython import const +""" +`adafruit_seesaw.samd09` - Pin definition for Adafruit SAMD09 Breakout with seesaw +================================================================================== +""" + +try: + from micropython import const +except ImportError: + def const(x): return x __version__ = "0.0.0-auto.0" __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_seesaw.git" @@ -37,11 +45,20 @@ _PWM_3_PIN = const(0x07) class SAMD09_Pinmap: + """This class is automatically used by `adafruit_seesaw.seesaw.Seesaw` when + a SAMD09 Breakout is detected. + + It is also a reference for the capabilities of each pin.""" + + """The pins capable of analog output""" analog_pins = (_ADC_INPUT_0_PIN, _ADC_INPUT_1_PIN, _ADC_INPUT_2_PIN, _ADC_INPUT_3_PIN) + """The effective bit resolution of the PWM pins""" pwm_width = 8 + """The pins capable of PWM output""" pwm_pins = (_PWM_0_PIN, _PWM_1_PIN, _PWM_2_PIN, _PWM_3_PIN) + """No pins on this board are capable of touch input""" touch_pins = () diff --git a/adafruit_seesaw/seesaw.py b/adafruit_seesaw/seesaw.py index 1675228..b55999f 100644 --- a/adafruit_seesaw/seesaw.py +++ b/adafruit_seesaw/seesaw.py @@ -20,7 +20,7 @@ # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN # THE SOFTWARE. """ -`seesaw` +`adafruit_seesaw.seesaw` ==================================================== An I2C to whatever helper chip. @@ -37,8 +37,8 @@ **Software and Dependencies:** -* Adafruit CircuitPython firmware for the ESP8622 and M0-based boards: - https://github.com/adafruit/circuitpython/releases +* Adafruit CircuitPython firmware: https://circuitpython.org/ +* or Adafruit Blinka: https://circuitpython.org/blinka * Adafruit's Bus Device library: https://github.com/adafruit/Adafruit_CircuitPython_BusDevice """ @@ -52,7 +52,11 @@ import struct except ImportError: import ustruct as struct -from micropython import const +try: + from micropython import const +except ImportError: + def const(x): return x + from adafruit_bus_device.i2c_device import I2CDevice __version__ = "0.0.0-auto.0" @@ -127,7 +131,8 @@ class Seesaw: """Driver for Seesaw i2c generic conversion trip :param ~busio.I2C i2c_bus: Bus the SeeSaw is connected to - :param int addr: I2C address of the SeeSaw device""" + :param int addr: I2C address of the SeeSaw device + :param ~digitalio.DigitalInOut drdy: Pin connected to SeeSaw's 'ready' output""" INPUT = const(0x00) OUTPUT = const(0x01) INPUT_PULLUP = const(0x02) @@ -165,35 +170,41 @@ def sw_reset(self): self.pin_mapping = SAMD09_Pinmap def get_options(self): + """Retrieve the 'options' word from the SeeSaw board""" buf = bytearray(4) self.read(_STATUS_BASE, _STATUS_OPTIONS, buf) ret = struct.unpack(">I", buf)[0] return ret def get_version(self): + """Retrieve the 'version' word from the SeeSaw board""" buf = bytearray(4) self.read(_STATUS_BASE, _STATUS_VERSION, buf) ret = struct.unpack(">I", buf)[0] return ret def pin_mode(self, pin, mode): + """Set the mode of a pin by number""" if pin >= 32: self.pin_mode_bulk_b(1 << (pin - 32), mode) else: self.pin_mode_bulk(1 << pin, mode) def digital_write(self, pin, value): + """Set the value of an output pin by number""" if pin >= 32: self.digital_write_bulk_b(1 << (pin - 32), value) else: self.digital_write_bulk(1 << pin, value) def digital_read(self, pin): + """Get the value of an input pin by number""" if pin >= 32: return self.digital_read_bulk_b((1 << (pin - 32))) != 0 return self.digital_read_bulk((1 << pin)) != 0 def digital_read_bulk(self, pins): + """Get the values of all the pins on the 'A' port as a bitmask""" buf = bytearray(4) self.read(_GPIO_BASE, _GPIO_BULK, buf) buf[0] = buf[0] & 0x3F @@ -201,6 +212,7 @@ def digital_read_bulk(self, pins): return ret & pins def digital_read_bulk_b(self, pins): + """Get the values of all the pins on the 'B' port as a bitmask""" buf = bytearray(8) self.read(_GPIO_BASE, _GPIO_BULK, buf) ret = struct.unpack(">I", buf[4:])[0] @@ -208,6 +220,7 @@ def digital_read_bulk_b(self, pins): def set_GPIO_interrupts(self, pins, enabled): + """Enable or disable the GPIO interrupt""" cmd = struct.pack(">I", pins) if enabled: self.write(_GPIO_BASE, _GPIO_INTENSET, cmd) @@ -215,6 +228,7 @@ def set_GPIO_interrupts(self, pins, enabled): self.write(_GPIO_BASE, _GPIO_INTENCLR, cmd) def analog_read(self, pin): + """Read the value of an analog pin by number""" buf = bytearray(2) if pin not in self.pin_mapping.analog_pins: raise ValueError("Invalid ADC pin") @@ -225,6 +239,7 @@ def analog_read(self, pin): return ret def touch_read(self, pin): + """Read the value of a touch pin by number""" buf = bytearray(2) if pin not in self.pin_mapping.touch_pins: @@ -235,6 +250,7 @@ def touch_read(self, pin): return ret def moisture_read(self): + """Read the value of the moisture sensor""" buf = bytearray(2) self.read(_TOUCH_BASE, _TOUCH_CHANNEL_OFFSET, buf, .005) @@ -275,12 +291,15 @@ def _pin_mode_bulk_x(self, capacity, offset, pins, mode): raise ValueError("Invalid pin mode") def pin_mode_bulk(self, pins, mode): + """Set the mode of all the pins on the 'A' port as a bitmask""" self._pin_mode_bulk_x(4, 0, pins, mode) def pin_mode_bulk_b(self, pins, mode): + """Set the mode of all the pins on the 'B' port as a bitmask""" self._pin_mode_bulk_x(8, 4, pins, mode) def digital_write_bulk(self, pins, value): + """Set the mode of pins on the 'A' port as a bitmask""" cmd = struct.pack(">I", pins) if value: self.write(_GPIO_BASE, _GPIO_BULK_SET, cmd) @@ -289,6 +308,7 @@ def digital_write_bulk(self, pins, value): def digital_write_bulk_b(self, pins, value): + """Set the mode of pins on the 'B' port as a bitmask""" cmd = bytearray(8) cmd[4:] = struct.pack(">I", pins) if value: @@ -297,6 +317,7 @@ def digital_write_bulk_b(self, pins, value): self.write(_GPIO_BASE, _GPIO_BULK_CLR, cmd) def analog_write(self, pin, value): + """Set the value of an analog output by number""" pin_found = False if self.pin_mapping.pwm_width == 16: if pin in self.pin_mapping.pwm_pins: @@ -313,6 +334,7 @@ def analog_write(self, pin, value): time.sleep(.001) def get_temp(self): + """Read the temperature""" buf = bytearray(4) self.read(_STATUS_BASE, _STATUS_TEMP, buf, .005) buf[0] = buf[0] & 0x3F @@ -320,6 +342,7 @@ def get_temp(self): return 0.00001525878 * ret def set_pwm_freq(self, pin, freq): + """Set the PWM frequency of a pin by number""" if pin in self.pin_mapping.pwm_pins: cmd = bytearray([self.pin_mapping.pwm_pins.index(pin), (freq >> 8), freq & 0xFF]) self.write(_TIMER_BASE, _TIMER_FREQ, cmd) @@ -343,36 +366,45 @@ def set_pwm_freq(self, pin, freq): # return self.read8(SEESAW_SERCOM0_BASE + sercom, SEESAW_SERCOM_DATA) def set_i2c_addr(self, addr): + """Store a new address in the device's EEPROM and reboot it.""" self.eeprom_write8(_EEPROM_I2C_ADDR, addr) time.sleep(.250) self.i2c_device.device_address = addr self.sw_reset() def get_i2c_addr(self): + """Return the device's I2C address stored in its EEPROM""" return self.read8(_EEPROM_BASE, _EEPROM_I2C_ADDR) def eeprom_write8(self, addr, val): + """Write a single byte directly to the device's EEPROM""" self.eeprom_write(addr, bytearray([val])) def eeprom_write(self, addr, buf): + """Write multiple bytes directly to the device's EEPROM""" self.write(_EEPROM_BASE, addr, buf) def eeprom_read8(self, addr): + """Read a single byte directly to the device's EEPROM""" return self.read8(_EEPROM_BASE, addr) def uart_set_baud(self, baud): + """Set the serial baudrate of the device""" cmd = struct.pack(">I", baud) self.write(_SERCOM0_BASE, _SERCOM_BAUD, cmd) def write8(self, reg_base, reg, value): + """Write an arbitrary I2C byte register on the device""" self.write(reg_base, reg, bytearray([value])) def read8(self, reg_base, reg): + """Read an arbitrary I2C byte register on the device""" ret = bytearray(1) self.read(reg_base, reg, ret) return ret[0] def read(self, reg_base, reg, buf, delay=.005): + """Read an arbitrary I2C register range on the device""" self.write(reg_base, reg) if self._drdy is not None: while self._drdy.value is False: @@ -383,6 +415,7 @@ def read(self, reg_base, reg, buf, delay=.005): i2c.readinto(buf) def write(self, reg_base, reg, buf=None): + """Write an arbitrary I2C register range on the device""" full_buffer = bytearray([reg_base, reg]) if buf is not None: full_buffer += buf diff --git a/adafruit_seesaw/tftshield18.py b/adafruit_seesaw/tftshield18.py index 14ede8d..09aae8b 100755 --- a/adafruit_seesaw/tftshield18.py +++ b/adafruit_seesaw/tftshield18.py @@ -21,9 +21,17 @@ # THE SOFTWARE. # pylint: disable=missing-docstring,invalid-name,too-many-public-methods +""" +`adafruit_seesaw.tftshield18` - Pin definitions for 1.8" TFT Shield V2 +====================================================================== +""" + from collections import namedtuple import board -from micropython import const +try: + from micropython import const +except ImportError: + def const(x): return x from adafruit_seesaw.seesaw import Seesaw __version__ = "0.0.0-auto.0" @@ -51,14 +59,21 @@ class TFTShield18(Seesaw): _BACKLIGHT_ON = b"\xFF\xFF" _BACKLIGHT_OFF = b"\x00\x00" - _button_mask = ((1 << _BUTTON_RIGHT) | - (1 << _BUTTON_DOWN) | - (1 << _BUTTON_LEFT) | - (1 << _BUTTON_UP) | - (1 << _BUTTON_SELECT) | - (1 << _BUTTON_A) | - (1 << _BUTTON_B) | - (1 << _BUTTON_C)) + try: + _button_mask = ((1 << _BUTTON_RIGHT) | + (1 << _BUTTON_DOWN) | + (1 << _BUTTON_LEFT) | + (1 << _BUTTON_UP) | + (1 << _BUTTON_SELECT) | + (1 << _BUTTON_A) | + (1 << _BUTTON_B) | + (1 << _BUTTON_C)) + except TypeError: +# During Sphinx build, the following error occurs: +# File "/home/jepler/src/Adafruit_CircuitPython_seesaw/adafruit_seesaw/tftshield18.py", line 60, in TFTShield18 +# (1 << _BUTTON_B) | +# TypeError: unsupported operand type(s) for <<: 'int' and '_MockObject' + _button_mask = 0xff def __init__(self, i2c_bus=board.I2C(), addr=0x2E): super(TFTShield18, self).__init__(i2c_bus, addr) diff --git a/docs/api.rst b/docs/api.rst index 88fde53..d307888 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -1,5 +1,39 @@ .. If you created a package, create one automodule per module in the package. +.. automodule:: adafruit_seesaw + :members: + .. automodule:: adafruit_seesaw.seesaw :members: + +.. automodule:: adafruit_seesaw.crickit + :members: + +.. automodule:: adafruit_seesaw.analoginput + :members: + +.. automodule:: adafruit_seesaw.digitalio + :members: + +.. automodule:: adafruit_seesaw.__init__ + :members: + +.. automodule:: adafruit_seesaw.keypad + :members: + +.. automodule:: adafruit_seesaw.neopixel + :members: + +.. automodule:: adafruit_seesaw.pwmout + :members: + +.. automodule:: adafruit_seesaw.robohat + :members: + +.. automodule:: adafruit_seesaw.samd09 + :members: + +.. automodule:: adafruit_seesaw.tftshield18 + :members: + diff --git a/docs/conf.py b/docs/conf.py index 20732c4..dbd03c5 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -18,7 +18,14 @@ # Uncomment the below if you use native CircuitPython modules such as # digitalio, micropython and busio. List the modules you use. Without it, the # autodoc module docs will fail to generate with a warning. -autodoc_mock_imports = [] +autodoc_mock_imports = ['adafruit_bus_device', 'digitalio', 'board'] + +autodoc_default_flags = ['special-members', 'members'] + +autodoc_default_options = { + 'member-order': 'bysource', + 'exclude-members': '__weakref__,__getnewargs__,__dict__,__module__,__init__', +} intersphinx_mapping = {'python': ('https://docs.python.org/3.4', None),'BusDevice': ('https://circuitpython.readthedocs.io/projects/busdevice/en/latest/', None),'Register': ('https://circuitpython.readthedocs.io/projects/register/en/latest/', None),'CircuitPython': ('https://circuitpython.readthedocs.io/en/latest/', None)} From 22432fe85a280e3f32784d0bc2526dfee6e6e61e Mon Sep 17 00:00:00 2001 From: Jeff Epler Date: Sat, 28 Dec 2019 21:24:58 -0600 Subject: [PATCH 2/3] Fix pylint fluff --- adafruit_seesaw/crickit.py | 3 ++- adafruit_seesaw/digitalio.py | 6 +++--- adafruit_seesaw/keypad.py | 11 ++++++----- adafruit_seesaw/neopixel.py | 6 ++++-- adafruit_seesaw/robohat.py | 11 ++++++----- adafruit_seesaw/samd09.py | 5 +++-- adafruit_seesaw/seesaw.py | 5 ++++- adafruit_seesaw/tftshield18.py | 5 +++-- 8 files changed, 31 insertions(+), 21 deletions(-) diff --git a/adafruit_seesaw/crickit.py b/adafruit_seesaw/crickit.py index 6f415e5..55b8ba0 100644 --- a/adafruit_seesaw/crickit.py +++ b/adafruit_seesaw/crickit.py @@ -29,7 +29,8 @@ try: from micropython import const except ImportError: - def const(x): return x + def const(x): + return x __version__ = "0.0.0-auto.0" __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_seesaw.git" diff --git a/adafruit_seesaw/digitalio.py b/adafruit_seesaw/digitalio.py index 7e77819..764c259 100644 --- a/adafruit_seesaw/digitalio.py +++ b/adafruit_seesaw/digitalio.py @@ -63,7 +63,7 @@ def switch_to_input(self, pull=None): """Switch the pin to input mode""" if pull == digitalio.Pull.DOWN: raise ValueError("Pull Down currently not supported") - elif pull == digitalio.Pull.UP: + if pull == digitalio.Pull.UP: self._seesaw.pin_mode(self._pin, self._seesaw.INPUT_PULLUP) else: self._seesaw.pin_mode(self._pin, self._seesaw.INPUT) @@ -116,9 +116,9 @@ def pull(self): def pull(self, mode): if self._direction == digitalio.Direction.OUTPUT: raise AttributeError("cannot set pull on an output pin") - elif mode == digitalio.Pull.DOWN: + if mode == digitalio.Pull.DOWN: raise ValueError("Pull Down currently not supported") - elif mode == digitalio.Pull.UP: + if mode == digitalio.Pull.UP: self._seesaw.pin_mode(self._pin, self._seesaw.INPUT_PULLUP) elif mode is None: self._seesaw.pin_mode(self._pin, self._seesaw.INPUT) diff --git a/adafruit_seesaw/keypad.py b/adafruit_seesaw/keypad.py index c05bb10..68e6f15 100644 --- a/adafruit_seesaw/keypad.py +++ b/adafruit_seesaw/keypad.py @@ -29,7 +29,8 @@ try: from micropython import const except ImportError: - def const(x): return x + def const(x): + return x from adafruit_seesaw.seesaw import Seesaw __version__ = "0.0.0-auto.0" @@ -63,13 +64,13 @@ class Keypad(Seesaw): :param int addr: I2C address of the SeeSaw device :param ~digitalio.DigitalInOut drdy: Pin connected to SeeSaw's 'ready' output""" - """Indicates that the key is currently pressed""" + #: Indicates that the key is currently pressed EDGE_HIGH = 0 - """Indicates that the key is currently released""" + #: Indicates that the key is currently released EDGE_LOW = 1 - """Indicates that the key was recently pressed""" + #: Indicates that the key was recently pressed EDGE_FALLING = 2 - """Indicates that the key was recently released""" + #: Indicates that the key was recently released EDGE_RISING = 3 def __init__(self, i2c_bus, addr=0x49, drdy=None): diff --git a/adafruit_seesaw/neopixel.py b/adafruit_seesaw/neopixel.py index 35586f6..92ea493 100644 --- a/adafruit_seesaw/neopixel.py +++ b/adafruit_seesaw/neopixel.py @@ -33,7 +33,8 @@ try: from micropython import const except ImportError: - def const(x): return x + def const(x): + return x __version__ = "1.2.3" __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_seesaw.git" @@ -66,7 +67,8 @@ class NeoPixel: :param int bpp: The number of bytes per pixel :param float brightness: The brightness, from 0.0 to 1.0 :param bool auto_write: Automatically update the pixels when changed - :param tuple pixel_order: The layout of the pixels. Use one of the order constants such as RGBW. + :param tuple pixel_order: The layout of the pixels. + Use one of the order constants such as RGBW. """ def __init__(self, seesaw, pin, n, *, bpp=3, brightness=1.0, auto_write=True, pixel_order=None): # TODO: brightness not yet implemented. diff --git a/adafruit_seesaw/robohat.py b/adafruit_seesaw/robohat.py index 12b9cbe..12985bf 100644 --- a/adafruit_seesaw/robohat.py +++ b/adafruit_seesaw/robohat.py @@ -29,7 +29,8 @@ try: from micropython import const except ImportError: - def const(x): return x + def const(x): + return x __version__ = "0.0.0-auto.0" __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_seesaw.git" @@ -89,22 +90,22 @@ class MM1_Pinmap: # analog[0]:47 analog[1]:48 analog[2]: analog[3]: # analog[4]: analog[5]: analog[6]: analog[7]: # - """The pins capable of analog output""" + #: The pins capable of analog output analog_pins = (_MM1_D3, _MM1_D2) - """The effective bit resolution of the PWM pins""" + #: The effective bit resolution of the PWM pins pwm_width = 16 # seesaw firmware (mm1_hat) pwm pin map: # pwm[0]:16 pwm[1]:17 pwm[2]:18 pwm[3]:19 pwm[4]:11 pwm[5]:10 # pwm[6]:9 pwm[7]:8 pwm[8]:40 pwm[9]:41 pwm[10]:42 pwm[11]:43 # - """The pins capable of PWM output""" + #: The pins capable of PWM output pwm_pins = (_MM1_SERVO1, _MM1_SERVO2, _MM1_SERVO3, _MM1_SERVO4, _MM1_SERVO5, _MM1_SERVO6, _MM1_SERVO7, _MM1_SERVO8, _MM1_D12, _MM1_D10, _MM1_D11, _MM1_D9) # seesaw firmware touch pin map: # touch[0]: 7 touch[1]: 6 touch[2]: 5 touch[3]: 4 - """The pins capable of touch input""" + #: The pins capable of touch input touch_pins = (_MM1_RCH1, _MM1_RCH2, _MM1_RCH3, _MM1_RCH4) diff --git a/adafruit_seesaw/samd09.py b/adafruit_seesaw/samd09.py index a10c9b2..67c7a03 100644 --- a/adafruit_seesaw/samd09.py +++ b/adafruit_seesaw/samd09.py @@ -29,7 +29,8 @@ try: from micropython import const except ImportError: - def const(x): return x + def const(x): + return x __version__ = "0.0.0-auto.0" __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_seesaw.git" @@ -50,7 +51,7 @@ class SAMD09_Pinmap: It is also a reference for the capabilities of each pin.""" - """The pins capable of analog output""" + #: The pins capable of analog output analog_pins = (_ADC_INPUT_0_PIN, _ADC_INPUT_1_PIN, _ADC_INPUT_2_PIN, _ADC_INPUT_3_PIN) diff --git a/adafruit_seesaw/seesaw.py b/adafruit_seesaw/seesaw.py index b55999f..6148a36 100644 --- a/adafruit_seesaw/seesaw.py +++ b/adafruit_seesaw/seesaw.py @@ -55,7 +55,8 @@ try: from micropython import const except ImportError: - def const(x): return x + def const(x): + return x from adafruit_bus_device.i2c_device import I2CDevice @@ -159,6 +160,7 @@ def sw_reset(self): .format(chip_id, _HW_ID_CODE)) pid = self.get_version() >> 16 + # pylint: disable=import-outside-toplevel if pid == _CRICKIT_PID: from adafruit_seesaw.crickit import Crickit_Pinmap self.pin_mapping = Crickit_Pinmap @@ -168,6 +170,7 @@ def sw_reset(self): else: from adafruit_seesaw.samd09 import SAMD09_Pinmap self.pin_mapping = SAMD09_Pinmap + # pylint: enable=import-outside-toplevel def get_options(self): """Retrieve the 'options' word from the SeeSaw board""" diff --git a/adafruit_seesaw/tftshield18.py b/adafruit_seesaw/tftshield18.py index 09aae8b..b3d54f4 100755 --- a/adafruit_seesaw/tftshield18.py +++ b/adafruit_seesaw/tftshield18.py @@ -31,7 +31,8 @@ try: from micropython import const except ImportError: - def const(x): return x + def const(x): + return x from adafruit_seesaw.seesaw import Seesaw __version__ = "0.0.0-auto.0" @@ -70,7 +71,7 @@ class TFTShield18(Seesaw): (1 << _BUTTON_C)) except TypeError: # During Sphinx build, the following error occurs: -# File "/home/jepler/src/Adafruit_CircuitPython_seesaw/adafruit_seesaw/tftshield18.py", line 60, in TFTShield18 +# File ".../tftshield18.py", line 60, in TFTShield18 # (1 << _BUTTON_B) | # TypeError: unsupported operand type(s) for <<: 'int' and '_MockObject' _button_mask = 0xff From 309d24896f9ac259dd2c63a810fb848b9b397650 Mon Sep 17 00:00:00 2001 From: Jeff Epler Date: Sat, 28 Dec 2019 21:45:11 -0600 Subject: [PATCH 3/3] remove pylint directive not understood by 1.9.2 --- adafruit_seesaw/seesaw.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/adafruit_seesaw/seesaw.py b/adafruit_seesaw/seesaw.py index 6148a36..5824a7d 100644 --- a/adafruit_seesaw/seesaw.py +++ b/adafruit_seesaw/seesaw.py @@ -160,7 +160,6 @@ def sw_reset(self): .format(chip_id, _HW_ID_CODE)) pid = self.get_version() >> 16 - # pylint: disable=import-outside-toplevel if pid == _CRICKIT_PID: from adafruit_seesaw.crickit import Crickit_Pinmap self.pin_mapping = Crickit_Pinmap @@ -170,7 +169,6 @@ def sw_reset(self): else: from adafruit_seesaw.samd09 import SAMD09_Pinmap self.pin_mapping = SAMD09_Pinmap - # pylint: enable=import-outside-toplevel def get_options(self): """Retrieve the 'options' word from the SeeSaw board"""