<reponame>swissinnovationlab/micropython_movement_notifier<gh_stars>0
# The MIT License (MIT)
#
# Copyright (c) 2017 <NAME>
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
# THE SOFTWARE.
"""
A MicroPython library for the Adafruit Sound Boards in UART mode!

This library has been adapted from the library written by Adafruit for Arduino,
available at https://github.com/adafruit/Adafruit_Soundboard_library.

* Author(s): <NAME>
"""

from machine import UART, Pin
from sys import platform as BOARD

__author__ = '<NAME>'
__license__ = 'MIT'
__copyright_ = 'Copyright 2017, Mike Mabey'

ESP8266 = 'esp8266'
PYBOARD = 'pyboard'
WIPY = 'wipy'

try:
    # Should be supported by all 3 supported boards
    from utime import sleep_ms
except ImportError:
    _supported = ', '.join([ESP8266, PYBOARD, WIPY])
    raise OSError('Unsupported board. Currently only works with {}.'.format(_supported))

SB_BAUD = 9600  # Baud rate of the sound boards
MIN_VOL = 0
MAX_VOL = 204
MAX_FILES = 25
DEBUG = False


class Soundboard:
    """Control an Adafruit Sound Board via UART.

    The :class:`Soundboard` class handles all communication with the sound
    board via :ref:`UART <upy:machine.UART>`, making it easy to get
    information about the sound files on the sound board and control playback.

    If you need to reset the sound board from your MicroPython code, be
    sure to provide the ``rst_pin`` parameter. The sound board sometimes gets
    out of UART mode and reverts to the factory default of GPIO trigger
    mode. When this happens, it will appear as if the sound board has
    stoped working for no apparent reason. This library is designed to
    automatically attempt resetting the board if a command fails, since
    that is a common cause. So, it is a good idea to provide this
    parameter.
    """

    def __init__(self, uart_id, rst_pin=None, vol=None, alt_get_files=False, debug=None, **uart_kwargs):
        """
        :param uart_id: ID for the :ref:`UART <upy:machine.UART>` bus to use.
            Acceptable values vary by board. Check the documentation for your
            board for more info.
        :param rst_pin: Identifier for the pin (on the MicroPython board)
            connected to the ``RST`` pin of the sound board. Valid identifiers
            vary by board.
        :param vol: Initial volume level to set. See :attr:`vol` for more info.
        :type vol: int or float
        :param bool alt_get_files: Uses an alternate method to get the list of
            track file names. See :meth:`use_alt_get_files` method for more
            info.
        :param bool debug: When not None, will set the debug output flag to the
            boolean value of this argument using the :meth:`toggle_debug`
            method.
        :param dict uart_kwargs: Additional values passed to the
            :ref:`UART.init() <upy:machine.UART>` method of the UART bus object.
            Acceptable values here also vary by board. It is not necessary to
            include the baud rate among these keyword values, because it will
            be set to ``SB_BAUD`` before the ``UART.init`` function is called.
        """
        if debug is not None:
            self.toggle_debug(bool(debug))

        self._uart = UART(uart_id, SB_BAUD)
        uart_kwargs['baudrate'] = SB_BAUD
        #self._uart.init(**uart_kwargs)
        self._files = None
        self._sizes = None
        self._lengths = None
        self._track = {}

        self._cur_vol = None
        self._cur_track = None
        self._reset_attempted = False

        # Setup reset pin
        if BOARD == PYBOARD:
            self._sb_rst = None if rst_pin is None else Pin(rst_pin, mode=Pin.OPEN_DRAIN, value=1)
        else:
            self._sb_rst = None if rst_pin is None else Pin(rst_pin, mode=Pin.IN)

        self.vol = vol

        if alt_get_files:
            self.use_alt_get_files()

    def _flush_uart_input(self):
        """Read any available data from the UART bus until none is left."""
        while self._uart.any():
            self._uart.read()

    def _send_simple(self, cmd, check=None, strip=True):
        """Send the command, optionally do a check on the output.

        The sound board understands the following commands:

        - ``L``: List files on the board
        - ``#``: Play a file by number
        - ``P``: Play a file by name
        - ``+``: Volume up (range is 0-204, increments of 2)
        - ``-``: Volume down
        - ``=``: Pause playback
        - ``>``: Un-pause playback
        - ``q``: Stop playback
        - ``t``: Give current position of playback and total time of track
        - ``s``: Current track size and total size

        :param cmd: Command to send over the UART bus. A newline character will
            be appended to the command before sending it, so it's not necessary
            to include one as part of the command.
        :type cmd: str or bytes
        :param check: Depending on the type of `check`, has three different
            behaviors. When None (default), the return value will be whatever
            the output from the command was. When a str or bytes, the return
            value will be True/False, indicating whether the command output
            starts with the value in `check`. When it otherwise evaluates to
            True, return value will be True/False, indicating the output
            started with the first character in `cmd`.
        :type check: str or bytes or None or bool
        :return: Varies depending on the value of `check`.
        :rtype: bytes or bool
        """
        self._flush_uart_input()
        cmd = cmd.strip()  # Make sure there's not more than one newline
        self._uart.write('{}\n'.format(cmd))
        if len(cmd) > 1:
            # We need to gobble the return when there's more than one character in the command
            self._uart.readline()
        try:
            msg = self._uart.readline()
            if strip:
                msg = msg.strip()
            assert isinstance(msg, bytes)
            printif(msg)
        except (AttributeError, AssertionError):
            if self._reset_attempted:
                # Only try resetting once
                return False  # TODO: Better way to handle failed commands? Too broad?
            printif('Got back None from a command. Attempting to restart the board to put it in UART mode.')
            self._reset_attempted = True
            self.reset()
            return self._send_simple(cmd, check)

        if check is None:
            return msg
        else:
            self._reset_attempted = True  # We already sent a command successfully

        if isinstance(check, str):
            return msg.startswith(check.encode())
        elif isinstance(check, bytes):
            return msg.startswith(check)
        elif check:
            return msg.startswith(cmd[0].encode())

    @property
    def files(self):
        """Return a ``list`` of the files on the sound board.

        :rtype: list
        """
        if self._files is None:
            self._get_files()
        return self._files

    @property
    def sizes(self):
        """Return a ``list`` of the files' sizes on the sound board.

        .. seealso:: :meth:`use_alt_get_files`

        :rtype: list
        """
        if self._sizes is None:
            self._get_files()
        return self._sizes

    def _get_files(self):
        """Ask the board for the files and their sizes, store the results."""
        self._flush_uart_input()

        self._files = []
        self._sizes = []
        self._uart.write('L\n')
        sleep_ms(10)
        i = 0
        while self._uart.any():
            msg = self._uart.readline().strip()
            printif(msg)
            fname, fsize = msg.split(b'\t')
            fname = fname.decode()
            self._files.append(fname)
            self._sizes.append(int(fsize))
            self._track[fname] = i
            i += 1

    def _get_files_alt(self):
        """Play every track, get info from feedback."""
        vol = self.vol
        self.vol = 0
        self._files = []
        self._lengths = []
        self._sizes = []
        for i in range(MAX_FILES):
            self.stop()
            msg = self._send_simple('#{}'.format(i))
            if msg.startswith(b'NoFile'):
                # Playing track i failed, it must not be a valid track number
                break
            play, track_num, fname = msg.split(b'\t')
            self._files.append(fname)
            self._track[fname] = i

            sleep_ms(50)
            sec = self.track_time()
            if sec:
                self._lengths.append(sec[1])
            else:
                self._lengths.append(0)
            size = self.track_size()
            if size:
                self._sizes.append(size[1])
            else:
                self._sizes.append(0)

        self.vol = vol

    @property
    def lengths(self):
        """Return a ``list`` of the track lengths in seconds.

        .. note::

            In my own testing of this method, the board always returns a value
            of zero seconds for the length for every track, no matter if it's a
            WAV or OGG file, short or long track.

        :rtype: list
        """
        if self._lengths is None:
            self._get_lengths()
        return self._lengths

    def _get_lengths(self):
        """Store the length of each track."""
        self._get_files_alt()

    def file_name(self, n):
        """Return the name of track ``n``.

        :param int n: Index of a file on the sound board or ``False`` if the
            track number doesn't exist.
        :return: Filename of track ``n``.
        :rtype: str or bool
        """
        try:
            return self.files[n]
        except IndexError:
            return False

    def track_num(self, file_name):
        """Return the track number of the given file name.

        :param str file_name: File name of the track. Should be one of the
            values from the :attr:`files` property.
        :return: The track number of the file name or ``False`` if not found.
        :rtype: int or bool
        """
        try:
            return self._track[file_name]
        except KeyError:
            return False

    def play(self, track=None):
        """Play a track on the board.

        :param track: The index (``int``) or filename (``str``) of the track to
            play.
        :type track: int or str
        :return: If the command was successful.
        :rtype: bool
        """
        if isinstance(track, int):
            cmd = '#'
            num = track
        elif isinstance(track, str):
            cmd = 'P'
            num = self.track_num(track)
        else:
            raise TypeError('You must specify a track by its number (int) or its name (str)')

        if self._send_simple('{}{}'.format(cmd, track), 'play'):
            self._cur_track = num
            return True
        return False

    def play_now(self, track):
        """Play a track on the board now, stopping current track if necessary.

        :param track: The index (``int``) or filename (``str``) of the track to
            play.
        :type track: int or str
        :return: If the command was successful.
        :rtype: bool
        """
        self.stop()
        if not self.play(track):
            # Playing the specified track failed, so just return False
            return False
        return True

    @property
    def vol(self):
        """Current volume.

        This is implemented as a class property, so you can get and set its
        value directly. When setting a new volume, you can use an ``int`` or a
        ``float`` (assuming your board supports floats). When setting to an
        ``int``, it should be in the range of 0-204. When set to a ``float``,
        the value will be interpreted as a percentage of :obj:`MAX_VOL`.

        :rtype: int
        """
        if self._cur_vol is None:
            self.vol_down()
        return self._cur_vol

    @vol.setter
    def vol(self, new_vol):
        if new_vol is None:
            return
        if isinstance(new_vol, float):
            new_vol = int(new_vol * MAX_VOL)
        if not isinstance(new_vol, int):
            printif('Invalid volume level. Try giving an int.')
            return
        elif new_vol > self.vol:
            self.vol_up(new_vol)
        elif new_vol < self.vol:
            self.vol_down(new_vol)

    def vol_up(self, vol=None):
        """Turn volume up by 2 points, return current volume level [0-204].

        :param int vol: Target volume. When not ``None``, volume will be turned
            up to be greater than or equal to this value.
        :rtype: int
        """
        global DEBUG
        printif('Turning volume up')
        if vol is None:
            self._cur_vol = int(self._send_simple('+'))
            return self._cur_vol
        if vol > MAX_VOL:
            printif('{} is above maximum volume. Setting to {} instead.'.format(vol, MAX_VOL))
            vol = MAX_VOL
        self._cur_vol = MIN_VOL - 1
        db = DEBUG
        DEBUG = False
        while vol > self._cur_vol:
            self._cur_vol = int(self._send_simple('+'))
        DEBUG = db
        return self._cur_vol

    def vol_down(self, vol=None):
        """Turn volume down by 2 points, return current volume level [0-204].

        :param int vol: Target volume. When not ``None``, volume will be turned
            down to be less than or equal to this value.
        :rtype: int
        """
        global DEBUG
        printif('Turning volume down')
        if vol is None:
            self._cur_vol = int(self._send_simple('-'))
            return self._cur_vol
        self._cur_vol = MAX_VOL + 1
        if vol < MIN_VOL:
            printif('{} is below minimum volume. Setting to {} instead.'.format(vol, MIN_VOL))
            vol = MIN_VOL
        db = DEBUG
        DEBUG = False
        while vol < self._cur_vol:
            self._cur_vol = int(self._send_simple('-'))
        DEBUG = db
        return self._cur_vol

    def pause(self):
        """Pause playback, return if the command was successful.

        :rtype: bool
        """
        return self._send_simple('=', True)

    def unpause(self):
        """Continue playback, return if the command was successful.

        :rtype: bool
        """
        return self._send_simple('>', True)

    def stop(self):
        """Stop playback, return if the command was successful.

        :rtype: bool
        """
        return self._send_simple('q', True)

    def track_time(self):
        """Return the current position of playback and total time of track.

        :rtype: tuple
        """
        msg = self._send_simple('t')
        if not msg:
            return -1, -1
        printif(len(msg))
        if len(msg) != 11:
            return False
        current, total = msg.decode('utf-8').split(':')
        return int(current), int(total)

    def track_size(self):
        """Return the remaining size and total size.

        It seems the remaining track size refers to the number of bytes left
        for the sound board to process before the playing of the track will be
        over.

        :return: Remaining track size and total size
        :rtype: tuple
        """
        msg = self._send_simple('s')
        if not msg:
            return -1, -1
        printif(len(msg))
        if len(msg) != 21:
            return False
        remaining, total = msg.decode('utf-8').split('/')
        return int(remaining), int(total)

    def reset(self):
        """Reset the sound board.

        Soft reset the board by bringing the ``RST`` pin low momentarily (10
        ms). This only has effect if the reset pin has been initialized in the
        constructor.

        Doing a soft reset on the board before doing any other actions can help
        ensure that it has been started in UART control mode, rather than GPIO
        trigger mode.

        .. seealso::

            `Soundboard Pinout <https://learn.adafruit.com/adafruit-audio-fx-sound-board/pinouts#uart-pins>`_
                Documentation on the sound boards' pinouts.


        :return: Whether the reset was successful. If the reset pin was not
            initialized in the constructor, this will always return ``False``.
        :rtype: bool
        """
        if self._sb_rst is None:
            # Don't attempt to restart the board if the reset pin wasn't initialized
            return False

        if BOARD == PYBOARD:
            self._sb_rst(0)
            sleep_ms(10)
            self._sb_rst(1)
        else:
            # Pin should already be in IN mode. This allows us to set the value we want to send, then switch to OUT mode
            # just long enough for the value to take effect, and finally switch back to IN mode.
            # self._sb_rst.value(0)
            self._sb_rst(0)
            self._sb_rst.mode(Pin.OUT)
            sleep_ms(10)
            self._sb_rst.mode(Pin.IN)

        sleep_ms(1000)  # Give the board some time to boot
        msg = self._uart.readline().strip()
        printif(msg)  # Blank line

        msg = self._uart.readline().strip()
        printif(msg)  # Date and name

        if not msg.startswith('Adafruit FX Sound Board'):
            return False

        sleep_ms(250)

        msg = self._uart.readline().strip()
        printif(msg)  # FAT type

        msg = self._uart.readline().strip()
        printif(msg)  # Number of files

        # Reset volume level and current track
        self.vol = self._cur_vol
        self._cur_track = None

        return True

    def use_alt_get_files(self, now=False):
        """Get list of track files using an alternate method.

        If the list of files is missing tracks you know are on the sound board,
        try calling this method. It doesn't depend on the sound board's internal
        command for returning a list of files. Instead, it plays each of the
        tracks using their track numbers and gets the filename and size from
        the output of the play command.

        :param bool now: When set to ``True``, the alternate method of getting
            the files list will be called immediately. Otherwise, the list of
            files will be populated the next time the :attr:`files` property is
            accessed (lazy loading).
        :rtype: None
        """
        self._get_files = self._get_files_alt
        if now:
            self._get_files()

    @staticmethod
    def toggle_debug(debug=None):
        """Turn on/off :obj:`DEBUG` flag.

        :param debug: If None, the :obj:`DEBUG` flag will be toggled to have the
            value opposite of its current value. Otherwise, :obj:`DEBUG` will be
            set to the boolean value of ``debug``.
        :rtype: None
        """
        global DEBUG
        if debug is None:
            DEBUG = not DEBUG
        else:
            DEBUG = bool(debug)


def printif(*values, **kwargs):
    """Print a message if :obj:`DEBUG` is set to ``True``."""
    print(*values, **kwargs) if DEBUG else None

# The MIT License (MIT)
#
# Copyright (c) 2017 <NAME>
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
# THE SOFTWARE.
"""
A MicroPython library for the Adafruit Sound Boards in UART mode!

This library has been adapted from the library written by Adafruit for Arduino,
available at https://github.com/adafruit/Adafruit_Soundboard_library.

* Author(s): <NAME>
"""

from machine import UART, Pin
from sys import platform as BOARD

__author__ = '<NAME>'
__license__ = 'MIT'
__copyright_ = 'Copyright 2017, Mike Mabey'

ESP8266 = 'esp8266'
PYBOARD = 'pyboard'
WIPY = 'wipy'

try:
    # Should be supported by all 3 supported boards
    from utime import sleep_ms
except ImportError:
    _supported = ', '.join([ESP8266, PYBOARD, WIPY])
    raise OSError('Unsupported board. Currently only works with {}.'.format(_supported))

SB_BAUD = 9600  # Baud rate of the sound boards
MIN_VOL = 0
MAX_VOL = 204
MAX_FILES = 25
DEBUG = False


class Soundboard:
    """Control an Adafruit Sound Board via UART.

    The :class:`Soundboard` class handles all communication with the sound
    board via :ref:`UART <upy:machine.UART>`, making it easy to get
    information about the sound files on the sound board and control playback.

    If you need to reset the sound board from your MicroPython code, be
    sure to provide the ``rst_pin`` parameter. The sound board sometimes gets
    out of UART mode and reverts to the factory default of GPIO trigger
    mode. When this happens, it will appear as if the sound board has
    stoped working for no apparent reason. This library is designed to
    automatically attempt resetting the board if a command fails, since
    that is a common cause. So, it is a good idea to provide this
    parameter.
    """

    def __init__(self, uart_id, rst_pin=None, vol=None, alt_get_files=False, debug=None, **uart_kwargs):
        """
        :param uart_id: ID for the :ref:`UART <upy:machine.UART>` bus to use.
            Acceptable values vary by board. Check the documentation for your
            board for more info.
        :param rst_pin: Identifier for the pin (on the MicroPython board)
            connected to the ``RST`` pin of the sound board. Valid identifiers
            vary by board.
        :param vol: Initial volume level to set. See :attr:`vol` for more info.
        :type vol: int or float
        :param bool alt_get_files: Uses an alternate method to get the list of
            track file names. See :meth:`use_alt_get_files` method for more
            info.
        :param bool debug: When not None, will set the debug output flag to the
            boolean value of this argument using the :meth:`toggle_debug`
            method.
        :param dict uart_kwargs: Additional values passed to the
            :ref:`UART.init() <upy:machine.UART>` method of the UART bus object.
            Acceptable values here also vary by board. It is not necessary to
            include the baud rate among these keyword values, because it will
            be set to ``SB_BAUD`` before the ``UART.init`` function is called.
        """
        if debug is not None:
            self.toggle_debug(bool(debug))

        self._uart = UART(uart_id, SB_BAUD)
        uart_kwargs['baudrate'] = SB_BAUD
        #self._uart.init(**uart_kwargs)
        self._files = None
        self._sizes = None
        self._lengths = None
        self._track = {}

        self._cur_vol = None
        self._cur_track = None
        self._reset_attempted = False

        # Setup reset pin
        if BOARD == PYBOARD:
            self._sb_rst = None if rst_pin is None else Pin(rst_pin, mode=Pin.OPEN_DRAIN, value=1)
        else:
            self._sb_rst = None if rst_pin is None else Pin(rst_pin, mode=Pin.IN)

        self.vol = vol

        if alt_get_files:
            self.use_alt_get_files()

    def _flush_uart_input(self):
        """Read any available data from the UART bus until none is left."""
        while self._uart.any():
            self._uart.read()

    def _send_simple(self, cmd, check=None, strip=True):
        """Send the command, optionally do a check on the output.

        The sound board understands the following commands:

        - ``L``: List files on the board
        - ``#``: Play a file by number
        - ``P``: Play a file by name
        - ``+``: Volume up (range is 0-204, increments of 2)
        - ``-``: Volume down
        - ``=``: Pause playback
        - ``>``: Un-pause playback
        - ``q``: Stop playback
        - ``t``: Give current position of playback and total time of track
        - ``s``: Current track size and total size

        :param cmd: Command to send over the UART bus. A newline character will
            be appended to the command before sending it, so it's not necessary
            to include one as part of the command.
        :type cmd: str or bytes
        :param check: Depending on the type of `check`, has three different
            behaviors. When None (default), the return value will be whatever
            the output from the command was. When a str or bytes, the return
            value will be True/False, indicating whether the command output
            starts with the value in `check`. When it otherwise evaluates to
            True, return value will be True/False, indicating the output
            started with the first character in `cmd`.
        :type check: str or bytes or None or bool
        :return: Varies depending on the value of `check`.
        :rtype: bytes or bool
        """
        self._flush_uart_input()
        cmd = cmd.strip()  # Make sure there's not more than one newline
        self._uart.write('{}\n'.format(cmd))
        if len(cmd) > 1:
            # We need to gobble the return when there's more than one character in the command
            self._uart.readline()
        try:
            msg = self._uart.readline()
            if strip:
                msg = msg.strip()
            assert isinstance(msg, bytes)
            printif(msg)
        except (AttributeError, AssertionError):
            if self._reset_attempted:
                # Only try resetting once
                return False  # TODO: Better way to handle failed commands? Too broad?
            printif('Got back None from a command. Attempting to restart the board to put it in UART mode.')
            self._reset_attempted = True
            self.reset()
            return self._send_simple(cmd, check)

        if check is None:
            return msg
        else:
            self._reset_attempted = True  # We already sent a command successfully

        if isinstance(check, str):
            return msg.startswith(check.encode())
        elif isinstance(check, bytes):
            return msg.startswith(check)
        elif check:
            return msg.startswith(cmd[0].encode())

    @property
    def files(self):
        """Return a ``list`` of the files on the sound board.

        :rtype: list
        """
        if self._files is None:
            self._get_files()
        return self._files

    @property
    def sizes(self):
        """Return a ``list`` of the files' sizes on the sound board.

        .. seealso:: :meth:`use_alt_get_files`

        :rtype: list
        """
        if self._sizes is None:
            self._get_files()
        return self._sizes

    def _get_files(self):
        """Ask the board for the files and their sizes, store the results."""
        self._flush_uart_input()

        self._files = []
        self._sizes = []
        self._uart.write('L\n')
        sleep_ms(10)
        i = 0
        while self._uart.any():
            msg = self._uart.readline().strip()
            printif(msg)
            fname, fsize = msg.split(b'\t')
            fname = fname.decode()
            self._files.append(fname)
            self._sizes.append(int(fsize))
            self._track[fname] = i
            i += 1

    def _get_files_alt(self):
        """Play every track, get info from feedback."""
        vol = self.vol
        self.vol = 0
        self._files = []
        self._lengths = []
        self._sizes = []
        for i in range(MAX_FILES):
            self.stop()
            msg = self._send_simple('#{}'.format(i))
            if msg.startswith(b'NoFile'):
                # Playing track i failed, it must not be a valid track number
                break
            play, track_num, fname = msg.split(b'\t')
            self._files.append(fname)
            self._track[fname] = i

            sleep_ms(50)
            sec = self.track_time()
            if sec:
                self._lengths.append(sec[1])
            else:
                self._lengths.append(0)
            size = self.track_size()
            if size:
                self._sizes.append(size[1])
            else:
                self._sizes.append(0)

        self.vol = vol

    @property
    def lengths(self):
        """Return a ``list`` of the track lengths in seconds.

        .. note::

            In my own testing of this method, the board always returns a value
            of zero seconds for the length for every track, no matter if it's a
            WAV or OGG file, short or long track.

        :rtype: list
        """
        if self._lengths is None:
            self._get_lengths()
        return self._lengths

    def _get_lengths(self):
        """Store the length of each track."""
        self._get_files_alt()

    def file_name(self, n):
        """Return the name of track ``n``.

        :param int n: Index of a file on the sound board or ``False`` if the
            track number doesn't exist.
        :return: Filename of track ``n``.
        :rtype: str or bool
        """
        try:
            return self.files[n]
        except IndexError:
            return False

    def track_num(self, file_name):
        """Return the track number of the given file name.

        :param str file_name: File name of the track. Should be one of the
            values from the :attr:`files` property.
        :return: The track number of the file name or ``False`` if not found.
        :rtype: int or bool
        """
        try:
            return self._track[file_name]
        except KeyError:
            return False

    def play(self, track=None):
        """Play a track on the board.

        :param track: The index (``int``) or filename (``str``) of the track to
            play.
        :type track: int or str
        :return: If the command was successful.
        :rtype: bool
        """
        if isinstance(track, int):
            cmd = '#'
            num = track
        elif isinstance(track, str):
            cmd = 'P'
            num = self.track_num(track)
        else:
            raise TypeError('You must specify a track by its number (int) or its name (str)')

        if self._send_simple('{}{}'.format(cmd, track), 'play'):
            self._cur_track = num
            return True
        return False

    def play_now(self, track):
        """Play a track on the board now, stopping current track if necessary.

        :param track: The index (``int``) or filename (``str``) of the track to
            play.
        :type track: int or str
        :return: If the command was successful.
        :rtype: bool
        """
        self.stop()
        if not self.play(track):
            # Playing the specified track failed, so just return False
            return False
        return True

    @property
    def vol(self):
        """Current volume.

        This is implemented as a class property, so you can get and set its
        value directly. When setting a new volume, you can use an ``int`` or a
        ``float`` (assuming your board supports floats). When setting to an
        ``int``, it should be in the range of 0-204. When set to a ``float``,
        the value will be interpreted as a percentage of :obj:`MAX_VOL`.

        :rtype: int
        """
        if self._cur_vol is None:
            self.vol_down()
        return self._cur_vol

    @vol.setter
    def vol(self, new_vol):
        if new_vol is None:
            return
        if isinstance(new_vol, float):
            new_vol = int(new_vol * MAX_VOL)
        if not isinstance(new_vol, int):
            printif('Invalid volume level. Try giving an int.')
            return
        elif new_vol > self.vol:
            self.vol_up(new_vol)
        elif new_vol < self.vol:
            self.vol_down(new_vol)

    def vol_up(self, vol=None):
        """Turn volume up by 2 points, return current volume level [0-204].

        :param int vol: Target volume. When not ``None``, volume will be turned
            up to be greater than or equal to this value.
        :rtype: int
        """
        global DEBUG
        printif('Turning volume up')
        if vol is None:
            self._cur_vol = int(self._send_simple('+'))
            return self._cur_vol
        if vol > MAX_VOL:
            printif('{} is above maximum volume. Setting to {} instead.'.format(vol, MAX_VOL))
            vol = MAX_VOL
        self._cur_vol = MIN_VOL - 1
        db = DEBUG
        DEBUG = False
        while vol > self._cur_vol:
            self._cur_vol = int(self._send_simple('+'))
        DEBUG = db
        return self._cur_vol

    def vol_down(self, vol=None):
        """Turn volume down by 2 points, return current volume level [0-204].

        :param int vol: Target volume. When not ``None``, volume will be turned
            down to be less than or equal to this value.
        :rtype: int
        """
        global DEBUG
        printif('Turning volume down')
        if vol is None:
            self._cur_vol = int(self._send_simple('-'))
            return self._cur_vol
        self._cur_vol = MAX_VOL + 1
        if vol < MIN_VOL:
            printif('{} is below minimum volume. Setting to {} instead.'.format(vol, MIN_VOL))
            vol = MIN_VOL
        db = DEBUG
        DEBUG = False
        while vol < self._cur_vol:
            self._cur_vol = int(self._send_simple('-'))
        DEBUG = db
        return self._cur_vol

    def pause(self):
        """Pause playback, return if the command was successful.

        :rtype: bool
        """
        return self._send_simple('=', True)

    def unpause(self):
        """Continue playback, return if the command was successful.

        :rtype: bool
        """
        return self._send_simple('>', True)

    def stop(self):
        """Stop playback, return if the command was successful.

        :rtype: bool
        """
        return self._send_simple('q', True)

    def track_time(self):
        """Return the current position of playback and total time of track.

        :rtype: tuple
        """
        msg = self._send_simple('t')
        if not msg:
            return -1, -1
        printif(len(msg))
        if len(msg) != 11:
            return False
        current, total = msg.decode('utf-8').split(':')
        return int(current), int(total)

    def track_size(self):
        """Return the remaining size and total size.

        It seems the remaining track size refers to the number of bytes left
        for the sound board to process before the playing of the track will be
        over.

        :return: Remaining track size and total size
        :rtype: tuple
        """
        msg = self._send_simple('s')
        if not msg:
            return -1, -1
        printif(len(msg))
        if len(msg) != 21:
            return False
        remaining, total = msg.decode('utf-8').split('/')
        return int(remaining), int(total)

    def reset(self):
        """Reset the sound board.

        Soft reset the board by bringing the ``RST`` pin low momentarily (10
        ms). This only has effect if the reset pin has been initialized in the
        constructor.

        Doing a soft reset on the board before doing any other actions can help
        ensure that it has been started in UART control mode, rather than GPIO
        trigger mode.

        .. seealso::

            `Soundboard Pinout <https://learn.adafruit.com/adafruit-audio-fx-sound-board/pinouts#uart-pins>`_
                Documentation on the sound boards' pinouts.


        :return: Whether the reset was successful. If the reset pin was not
            initialized in the constructor, this will always return ``False``.
        :rtype: bool
        """
        if self._sb_rst is None:
            # Don't attempt to restart the board if the reset pin wasn't initialized
            return False

        if BOARD == PYBOARD:
            self._sb_rst(0)
            sleep_ms(10)
            self._sb_rst(1)
        else:
            # Pin should already be in IN mode. This allows us to set the value we want to send, then switch to OUT mode
            # just long enough for the value to take effect, and finally switch back to IN mode.
            # self._sb_rst.value(0)
            self._sb_rst(0)
            self._sb_rst.mode(Pin.OUT)
            sleep_ms(10)
            self._sb_rst.mode(Pin.IN)

        sleep_ms(1000)  # Give the board some time to boot
        msg = self._uart.readline().strip()
        printif(msg)  # Blank line

        msg = self._uart.readline().strip()
        printif(msg)  # Date and name

        if not msg.startswith('Adafruit FX Sound Board'):
            return False

        sleep_ms(250)

        msg = self._uart.readline().strip()
        printif(msg)  # FAT type

        msg = self._uart.readline().strip()
        printif(msg)  # Number of files

        # Reset volume level and current track
        self.vol = self._cur_vol
        self._cur_track = None

        return True

    def use_alt_get_files(self, now=False):
        """Get list of track files using an alternate method.

        If the list of files is missing tracks you know are on the sound board,
        try calling this method. It doesn't depend on the sound board's internal
        command for returning a list of files. Instead, it plays each of the
        tracks using their track numbers and gets the filename and size from
        the output of the play command.

        :param bool now: When set to ``True``, the alternate method of getting
            the files list will be called immediately. Otherwise, the list of
            files will be populated the next time the :attr:`files` property is
            accessed (lazy loading).
        :rtype: None
        """
        self._get_files = self._get_files_alt
        if now:
            self._get_files()

    @staticmethod
    def toggle_debug(debug=None):
        """Turn on/off :obj:`DEBUG` flag.

        :param debug: If None, the :obj:`DEBUG` flag will be toggled to have the
            value opposite of its current value. Otherwise, :obj:`DEBUG` will be
            set to the boolean value of ``debug``.
        :rtype: None
        """
        global DEBUG
        if debug is None:
            DEBUG = not DEBUG
        else:
            DEBUG = bool(debug)


def printif(*values, **kwargs):
    """Print a message if :obj:`DEBUG` is set to ``True``."""
    print(*values, **kwargs) if DEBUG else None
# The MIT License (MIT) # # Copyright (c) 2017 <NAME> # # Permission is hereby granted, free of charge, to any person obtaining a copy # of this software and associated documentation files (the "Software"), to deal # in the Software without restriction, including without limitation the rights # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell # copies of the Software, and to permit persons to whom the Software is # furnished to do so, subject to the following conditions: # # The above copyright notice and this permission notice shall be included in # all copies or substantial portions of the Software. # # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN # THE SOFTWARE. A MicroPython library for the Adafruit Sound Boards in UART mode!  This library has been adapted from the library written by Adafruit for Arduino, available at https://github.com/adafruit/Adafruit_Soundboard_library.  * Author(s): <NAME> # Should be supported by all 3 supported boards # Baud rate of the sound boards Control an Adafruit Sound Board via UART.      The :class:`Soundboard` class handles all communication with the sound     board via :ref:`UART <upy:machine.UART>`, making it easy to get     information about the sound files on the sound board and control playback.      If you need to reset the sound board from your MicroPython code, be     sure to provide the ``rst_pin`` parameter. The sound board sometimes gets     out of UART mode and reverts to the factory default of GPIO trigger     mode. When this happens, it will appear as if the sound board has     stoped working for no apparent reason. This library is designed to     automatically attempt resetting the board if a command fails, since     that is a common cause. So, it is a good idea to provide this     parameter. :param uart_id: ID for the :ref:`UART <upy:machine.UART>` bus to use.             Acceptable values vary by board. Check the documentation for your             board for more info.         :param rst_pin: Identifier for the pin (on the MicroPython board)             connected to the ``RST`` pin of the sound board. Valid identifiers             vary by board.         :param vol: Initial volume level to set. See :attr:`vol` for more info.         :type vol: int or float         :param bool alt_get_files: Uses an alternate method to get the list of             track file names. See :meth:`use_alt_get_files` method for more             info.         :param bool debug: When not None, will set the debug output flag to the             boolean value of this argument using the :meth:`toggle_debug`             method.         :param dict uart_kwargs: Additional values passed to the             :ref:`UART.init() <upy:machine.UART>` method of the UART bus object.             Acceptable values here also vary by board. It is not necessary to             include the baud rate among these keyword values, because it will             be set to ``SB_BAUD`` before the ``UART.init`` function is called. #self._uart.init(**uart_kwargs) # Setup reset pin Read any available data from the UART bus until none is left. Send the command, optionally do a check on the output.          The sound board understands the following commands:          - ``L``: List files on the board         - ``#``: Play a file by number         - ``P``: Play a file by name         - ``+``: Volume up (range is 0-204, increments of 2)         - ``-``: Volume down         - ``=``: Pause playback         - ``>``: Un-pause playback         - ``q``: Stop playback         - ``t``: Give current position of playback and total time of track         - ``s``: Current track size and total size          :param cmd: Command to send over the UART bus. A newline character will             be appended to the command before sending it, so it's not necessary             to include one as part of the command.         :type cmd: str or bytes         :param check: Depending on the type of `check`, has three different             behaviors. When None (default), the return value will be whatever             the output from the command was. When a str or bytes, the return             value will be True/False, indicating whether the command output             starts with the value in `check`. When it otherwise evaluates to             True, return value will be True/False, indicating the output             started with the first character in `cmd`.         :type check: str or bytes or None or bool         :return: Varies depending on the value of `check`.         :rtype: bytes or bool # Make sure there's not more than one newline # We need to gobble the return when there's more than one character in the command # Only try resetting once # TODO: Better way to handle failed commands? Too broad? # We already sent a command successfully Return a ``list`` of the files on the sound board.          :rtype: list Return a ``list`` of the files' sizes on the sound board.          .. seealso:: :meth:`use_alt_get_files`          :rtype: list Ask the board for the files and their sizes, store the results. Play every track, get info from feedback. # Playing track i failed, it must not be a valid track number Return a ``list`` of the track lengths in seconds.          .. note::              In my own testing of this method, the board always returns a value             of zero seconds for the length for every track, no matter if it's a             WAV or OGG file, short or long track.          :rtype: list Store the length of each track. Return the name of track ``n``.          :param int n: Index of a file on the sound board or ``False`` if the             track number doesn't exist.         :return: Filename of track ``n``.         :rtype: str or bool Return the track number of the given file name.          :param str file_name: File name of the track. Should be one of the             values from the :attr:`files` property.         :return: The track number of the file name or ``False`` if not found.         :rtype: int or bool Play a track on the board.          :param track: The index (``int``) or filename (``str``) of the track to             play.         :type track: int or str         :return: If the command was successful.         :rtype: bool Play a track on the board now, stopping current track if necessary.          :param track: The index (``int``) or filename (``str``) of the track to             play.         :type track: int or str         :return: If the command was successful.         :rtype: bool # Playing the specified track failed, so just return False Current volume.          This is implemented as a class property, so you can get and set its         value directly. When setting a new volume, you can use an ``int`` or a         ``float`` (assuming your board supports floats). When setting to an         ``int``, it should be in the range of 0-204. When set to a ``float``,         the value will be interpreted as a percentage of :obj:`MAX_VOL`.          :rtype: int Turn volume up by 2 points, return current volume level [0-204].          :param int vol: Target volume. When not ``None``, volume will be turned             up to be greater than or equal to this value.         :rtype: int Turn volume down by 2 points, return current volume level [0-204].          :param int vol: Target volume. When not ``None``, volume will be turned             down to be less than or equal to this value.         :rtype: int Pause playback, return if the command was successful.          :rtype: bool Continue playback, return if the command was successful.          :rtype: bool Stop playback, return if the command was successful.          :rtype: bool Return the current position of playback and total time of track.          :rtype: tuple Return the remaining size and total size.          It seems the remaining track size refers to the number of bytes left         for the sound board to process before the playing of the track will be         over.          :return: Remaining track size and total size         :rtype: tuple Reset the sound board.          Soft reset the board by bringing the ``RST`` pin low momentarily (10         ms). This only has effect if the reset pin has been initialized in the         constructor.          Doing a soft reset on the board before doing any other actions can help         ensure that it has been started in UART control mode, rather than GPIO         trigger mode.          .. seealso::              `Soundboard Pinout <https://learn.adafruit.com/adafruit-audio-fx-sound-board/pinouts#uart-pins>`_                 Documentation on the sound boards' pinouts.           :return: Whether the reset was successful. If the reset pin was not             initialized in the constructor, this will always return ``False``.         :rtype: bool # Don't attempt to restart the board if the reset pin wasn't initialized # Pin should already be in IN mode. This allows us to set the value we want to send, then switch to OUT mode # just long enough for the value to take effect, and finally switch back to IN mode. # self._sb_rst.value(0) # Give the board some time to boot # Blank line # Date and name # FAT type # Number of files # Reset volume level and current track Get list of track files using an alternate method.          If the list of files is missing tracks you know are on the sound board,         try calling this method. It doesn't depend on the sound board's internal         command for returning a list of files. Instead, it plays each of the         tracks using their track numbers and gets the filename and size from         the output of the play command.          :param bool now: When set to ``True``, the alternate method of getting             the files list will be called immediately. Otherwise, the list of             files will be populated the next time the :attr:`files` property is             accessed (lazy loading).         :rtype: None Turn on/off :obj:`DEBUG` flag.          :param debug: If None, the :obj:`DEBUG` flag will be toggled to have the             value opposite of its current value. Otherwise, :obj:`DEBUG` will be             set to the boolean value of ``debug``.         :rtype: None Print a message if :obj:`DEBUG` is set to ``True``.