Added auto-Windows support and Windows installation docs

Author: Thomas Preston

CHANGELOG

@@ -1,6 +1,20 @@
 Change Log
 ==========
 
+v0.8.4
+------
+- Default serial port is set to blank on error and added 'requires' to
+  setup.py
+- Added new installation docs.
+
+v0.8.3
+------
+- Nicer error message for Windows/OSX.
+
+v0.8.2
+------
+- More robust OS and serial port check.
+
 v0.8.1
 ------
 - Figures out default serial port for Raspberry Pi 2 and below,

codebug_tether/core.py

@@ -1,17 +1,55 @@
+from __future__ import print_function
 import os
+import sys
+import glob
 import time
 import serial
 import struct
 from codebug_tether.i2c import *
 from codebug_tether.serial_channel_device import SerialChannelDevice
 
 
-# setup default serial port (different on MacOS and >=Raspberry Pi 3)
-if os.uname().sysname == 'Darwin':
-    # OSX
-    DEFAULT_SERIAL_PORT = '/dev/tty.USBmodem'
+########################################################################
+# setup DEFAULT_SERIAL_PORT which is different on Windows, MacOS,
+# Raspberry Pi 2 and Raspberry Pi 3
+if sys.platform.startswith('win') or sys.platform.startswith('darwin'):
+    # On Windows or OSX take the first serial port we can find
+    def serial_ports():
+        """ Lists serial port names
+
+            :raises EnvironmentError:
+                On unsupported or unknown platforms
+            :returns:
+                A list of the serial ports available on the system
+        """
+        if sys.platform.startswith('win'):
+            ports = ['COM%s' % (i + 1) for i in range(256)]
+        elif (sys.platform.startswith('linux') or
+                sys.platform.startswith('cygwin')):
+            # this excludes your current terminal "/dev/tty"
+            ports = glob.glob('/dev/tty[A-Za-z0-9]*')
+        elif sys.platform.startswith('darwin'):
+            ports = glob.glob('/dev/tty.*')
+        else:
+            raise EnvironmentError('Unsupported platform')
+
+        result = []
+        for port in ports:
+            try:
+                s = serial.Serial(port)
+                s.close()
+                result.append(port)
+            except (OSError, serial.SerialException):
+                pass
+        return result
+    # use the first one
+    try:
+        DEFAULT_SERIAL_PORT = serial_ports()[0]
+    except IndexError:
+        print('ERROR: Could not find any serial ports.', file=sys.stderr)
+        DEFAULT_SERIAL_PORT = ''
 else:
-    # assume we're on Raspberry Pi/Linux
+    # otherwise assume we're on Raspberry Pi/Linux
     def get_rpi_revision():
         """Returns the version number from the revision line."""
         for line in open("/proc/cpuinfo"):
@@ -20,13 +58,15 @@ def get_rpi_revision():
                 return re.sub('Revision\t: ([a-z0-9]+)\n', r'\1', line)
 
     rpi_revision = get_rpi_revision()
-    if rpi_revision and rpi_revision != 'Beta' and int('0x'+rpi_revision, 16) >= 0xa02082:
+    if (rpi_revision and
+            (rpi_revision != 'Beta') and
+            (int('0x'+rpi_revision, 16) >= 0xa02082)):
         # RPi 3 and above
         DEFAULT_SERIAL_PORT = '/dev/ttyS0'
     else:
         # RPi 2 and below
         DEFAULT_SERIAL_PORT = '/dev/ttyACM0'
-
+########################################################################
 
 IO_DIGITAL_OUTPUT = 0
 IO_DIGITAL_INPUT = 1

codebug_tether/version.py

@@ -1 +1 @@
-__version__ = '0.8.1'
+__version__ = '0.8.4'

docs/conf.py

@@ -50,9 +50,11 @@
 #
 # The short X.Y version.
 # The short X.Y version.
-version = '0.8.1'
+# NOTE: this is the version of the firmware download too so don't change
+# this with minor changes in the software if the firmware hasn't changed!
+version = '0.8.0'
 # The full version, including alpha/beta/rc tags.
-release = '0.8.1'
+release = '0.8.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/installation.rst

@@ -1,85 +1,134 @@
 ############
 Installation
 ############
-You can use the ``codebug_tether`` Python 3 API by either:
 
-* Installing with ``pip``
-* Copying the ``codebug_tether`` module into your project directory.
+Setting up CodeBug
+==================
+In order to use CodeBug with codebug_tether you need to program CodeBug
+with ``codebug_tether.cbg`` (|firmwaredownload|).
 
-CodeBug Tether depends on pyserial.
+To do this, hold down button A and plug in CodeBug via USB --- it should
+appear as a USB drive --- then copy the ``codebug_tether.cbg`` file onto it.
+CodeBug is now ready to be used via serial USB. Press button B to exit
+programming mode.
 
-It is reccomended that you install using virtual environments.
+.. note:: When CodeBug is connected to a computer via USB is should now
+          appear as a serial device. To reprogram CodeBug: hold down
+          button A and (re)plug it into a USB port.
 
 
-Setting up CodeBug
-------------------
-In order to communicate with CodeBug over Serial USB you need to program CodeBug with
-``codebug_tether.cbg`` (|firmwaredownload|).
-To do this, plug in CodeBug via USB while holding button A --- it should
-appear as a USB drive --- then copy onto it the ``codebug_tether.cbg`` file.
-CodeBug is now ready to be used via serial USB. Press button B to exit
-programming mode.
+Install codebug_tether on Windows
+=================================
+.. note:: These instructions are based on `The Hitchhikers Guide to Python: Installing Python on Windows <http://docs.python-guide.org/en/latest/starting/install/win/>`_
+
+Install Python
+--------------
+Download and install the latest verson of Python 3 from `here <https://www.python.org/downloads/windows/>`_.
+Make sure you tick the *Add Python 3 to environment variables* checkbox.
+
+Install codebug_tether
+----------------------
+To install codebug_tether, open up a command prompt and type::
+
+    pip install codebug_tether
+
+To test it has worked, plug in CodeBug and open a Python shell by typing::
+
+    python
+
+Your command prompt should have changed to::
+
+    >>> _
+
+Now type::
+
+    >>> import codebug_tether
+    >>> codebug = codebug_tether.CodeBug()
+    >>> codebug.set_pixel(2, 2, 1)
+
+The middle pixel on your CodeBug should light up.
+
+
+Install codebug_tether on OSX
+=============================
+.. note:: These instructions are based on `The Hitchhikers Guide to Python: Installing Python on Mac OS X <http://docs.python-guide.org/en/latest/starting/install/osx/>`_
 
-When CodeBug is connected to a computer via USB is should now appear as a
-serial device (``/dev/ttyACM0`` on Linux).
+Install Python
+--------------
+Download and install `Xcode <https://developer.apple.com/xcode/download/>`_ (if you haven't already) and then enable the command line tools by running (in a terminal)::
 
+    xcode-select --install
 
+Now install Homebrew (a package manager for OSX)::
 
-Installing with ``pip``
------------------------
-.. warning:: Consider using virtual environments.
+    /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
 
-Make sure ``pip`` is installed::
+The script will explain what changes it will make and prompt you before the installation begins. Once you’ve installed Homebrew, insert the Homebrew directory at the top of your **PATH** environment variable. You can do this by adding the following line at the bottom of your ~/.profile file::
 
-    sudo apt-get install python3-pip
+    export PATH=/usr/local/bin:/usr/local/sbin:$PATH
 
-Install ``codebug_tether`` using ``pip``::
+Now, we can install Python 3::
 
-    sudo pip-3.2 install pyserial codebug_tether
+    brew install python3
 
+This will take a minute or two.
 
-Installing with ``pip`` (with Virtual Environments)
----------------------------------------------------
-.. note :: Generally, it's best to install packages into a
-           `virtual environment <http://docs.python-guide.org/en/latest/dev/virtualenvs/>`_
-           when using ``pip`` so that they remain project specific.
+Install codebug_tether
+----------------------
+To install codebug_tether, open up a terminal and type::
 
-Install ``virtualenv``::
+    pip install codebug_tether
 
-    sudo pip-3.2 install virtualenv
+To test it has worked, plug in CodeBug and open a Python shell by typing::
 
-Move into your project and create the virtual environment::
+    python
 
-    cd my_project_directory/
-    virtualenv-3.2 venv
+Your command prompt should have changed to::
+
+    >>> _
+
+Now type::
+
+    >>> import codebug_tether
+    >>> codebug = codebug_tether.CodeBug()
+    >>> codebug.set_pixel(2, 2, 1)
 
-Activate the virtual environment::
+The middle pixel on your CodeBug should light up.
 
-    source venv/bin/activate
 
-You should notice that your command prompt has changed. ``pip`` will now
-install all packages into the virtual environment instead of littering
-your system files::
+Install codebug_tether on Linux
+===============================
+Install Python
+--------------
+Python should already be installed but for good measure::
 
-    pip install pyserial codebug_tether
+    sudo apt-get install python3
 
-Now you can work on your application with ``codebug_tether``. Once
-you're done, deactivate the virtual environment::
+To install pip, securely download `get-pip.py <https://bootstrap.pypa.io/get-pip.py>`_.
 
-    deactivate
+Then run the following::
 
-You will not be able to use packages installed in the virtual environment
-until you activate it again (`source venv/bin/activate`).
+    python get-pip.py
 
 
-Using ``codebug_tether`` without installing
------------------------------------------------
-You may want to use ``codebug_tether`` without installing anything at
-all. You can just download and include the ``codebug_tether`` package
-in your project and start using it. The quickest way to do this is::
+Install codebug_tether
+----------------------
+To install codebug_tether, open up a terminal and type::
+
+    pip install codebug_tether
+
+To test it has worked, plug in CodeBug and open a Python shell by typing::
+
+    python
+
+Your command prompt should have changed to::
+
+    >>> _
+
+Now type::
 
-    git clone https://github.com/codebugtools/codebug_tether.git
-    cp -r codebug_tether/codebug_tether myproject/
-    cd myproject/
-    python3
     >>> import codebug_tether
+    >>> codebug = codebug_tether.CodeBug()
+    >>> codebug.set_pixel(2, 2, 1)
+
+The middle pixel on your CodeBug should light up.

setup.py

@@ -27,6 +27,7 @@ def get_version():
     license='GPLv3+',
     url='https://github.com/codebugtools/codebug_tether',
     packages=['codebug_tether'],
+    requires=['pyserial'],
     long_description=open('README.md').read() + open('CHANGELOG').read(),
     classifiers=[
         "License :: OSI Approved :: GNU Affero General Public License v3 or "