Help on module modio:

NAME
    modio - Utility functions and classes to handle olimex mod-io from python.

FILE
    modio.py

DESCRIPTION
    SETUP
    =====
    
    Before using this code, you need to make sure mod-io is configured and working
    on your system. Assuming you have a debian based system (like ubuntu or
    raspbian):
    
    1) edit /etc/modules, by running 'sudo -s' and opening the file with your
       favourite editor. Make sure it has the lines:
    
         # ... random comments ...
         i2c-dev
         i2c_bcm2708 baudrate=50000
    
    2) once /etc/modules has been edited, run:
      
         $ sudo service kmod start
    
       to load all the modules. Alternatively, you can reboot your system.
    
    3) make sure debugging tools and libraries are installed:
    
         $ sudo apt-get install i2c-tools python-smbus 
    
    3) verify that mod-io is accessible, and to which bus it is
       connected. You need to run
    
         $ sudo i2cdetect -y X
    
       with X being 0 or 1. X is the bus number. If you see a 58 (assuming you did
       not change the default address of mod-io) in the output, you found the right
       bus. Remember this number for later!
       
       If you don't see 58 anywhere, do you see some other number? Did you change
       mod-io address or firmware? Is it plugged correctly?  Is there a flashing
       orange led? If not, you may have problems with the firmware, power supply or
       connection of mod-io.
    
       Example:
       
       Check status of bus 0. There are all dashesh, mod-io is not here.
    
         $ sudo i2cdetect -y 0
    
                0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
           00:          -- -- -- -- -- -- -- -- -- -- -- -- -- 
           10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
           20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
           30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
           40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
           50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
           60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
           70: -- -- -- -- -- -- -- --                         
    
       Check status of bus 1. You can see mod-io on address 58! Good!
    
         $ sudo i2cdetect -y 1
    
                0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
           00:          -- -- -- -- -- -- -- -- -- -- -- -- -- 
           10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
           20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
           30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
           40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
           50: -- -- -- -- -- -- -- -- 58 -- -- -- -- -- -- -- 
           60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
           70: -- -- -- -- -- -- -- --         
    
    
    HOW TO USE THE LIBRARY
    ======================
    
    1) Copy the modio.py file or the whole directory next to
       your .py script, or somewhere in PYTHONPATH.
    
    2) Import it with 'import modio' or 'from modio import modio'
       if you left the whole directory.
    
    3) Use it! Examples:
    
        from modio import modio
        
        # BUS Number is the bus you found during setup, see instructions above!
        board = modio.Device(bus=1)
        
        # Take control of the first relay (number 1 on board)
        relay = modio.Relay(board, 1)
        
        # Turn it on!
        relay.CloseContact()
        
        # Check relay status.
        if relay.IsClosed():
          print "Relay is on"
        else:
          print "Relay is off"
        
        # Turn it off!
        relay.OpenContact()
    
    
    MODIFIED FIRMWARE
    =================
    
    If you have a mod-io and would like some extra features from your
    board you can install a modified firmware available here:
    
      https://github.com/ccontavalli/olimex-modio-firmware
    
    This firmware allows you to:
    
      1. Read which extra features the firmware supports :)
      2. Read the state of relays directly from the board.
         (thanks to Imran for the patches, https://github.com/emnuu)
    
    
    PROBLEMS, ISSUES, or QUESTIONS?
    ===============================
    
    Check out the wiki here:
      https://github.com/ccontavalli/python-olimex-modio/wiki
    
    File problems, issues or other requests here:
      https://github.com/ccontavalli/python-olimex-modio/issues
    
    Newer versions of the code are available here:
      https://github.com/ccontavalli/python-olimex-modio

CLASSES
    __builtin__.object
        Device
        DigitalIn
        FakeBus
        Relay
        SmbBus
    exceptions.IOError(exceptions.EnvironmentError)
        DeviceNotFoundException
        SMBBusNotConfiguredProperly
    
    class Device(__builtin__.object)
     |  Represents a mod-io device, allows to perform common operations.
     |  
     |  Methods defined here:
     |  
     |  ChangeAddress(self, new_address)
     |      Changes the address of modio.
     |      
     |      Args:
     |        new_address: int, 0 - 0xff, the new address to be assigned
     |          to modio.
     |      
     |      Raises:
     |        ValueError, if the new_address is invalid.
     |  
     |  CloseContactRelay(self, relay)
     |      CloseContact a specific relay.
     |      
     |      Args:
     |        relay: int, 1 - 4, the relay to enable. Note that olimex
     |          mod-io has exactly 4 relays.
     |      
     |      Raises:
     |        ValueError if an invalid relay number is passed.
     |  
     |  GetDigitalIn(self, digital_in)
     |      Return value for digital in.
     |      
     |      Args:
     |        digital_in: int, 0 - 3, the digital in value to get for. Note that olimex
     |          mod-io has exactly 4 digital ins.
     |      
     |      Raises:
     |        ValueError if an invalid digital in number is passed.
     |      
     |      Returns:
     |        False if the digital in is low, True if high.
     |  
     |  GetDigitalIns(self)
     |      Reads the values of digital in register.
     |  
     |  GetReadAinCommand(self, ain)
     |      Returns the command to use to read an analogic input.
     |      
     |      Args:
     |        ain: integer, the number of the analogic input to read.
     |            On mod-io, analg inputs are numbered 1 - 4.
     |      
     |      Raises:
     |        ValueError: if an invalid analog input is passed.
     |      
     |      Returns:
     |        integer, the command to use to read the analog input.
     |  
     |  GetRelayBit(self, relay)
     |      Returns the bit that represents the status of the specified relay.
     |      
     |      With mod-io, the status of all the relays on the board is represented
     |      as a bit mask. Each bit to 0 represents an open relay, and each bit to 1
     |      representis a closed relay. This value can be written to mod-io to close
     |      / open all relays.
     |      
     |      This method takes a relay number (eg, 1 - 4) and returns an integer
     |      with the bit controlling this relay set to 1. As this method raises
     |      ValueError if an invalid relay is provided, it can be used to validate
     |      relay numbers.
     |      
     |      Args:
     |        relay: int, 1 - 4, the relay to . Note that olimex
     |          mod-io has exactly 4 relays.
     |      
     |      Returns:
     |        int, the bit of the relay. For relay 0, 1, for relay 1, 2, and
     |        so on. Mostly useful as this function validates the number.
     |      
     |      Raises:
     |        ValueError, if the relay number is invalid.
     |  
     |  GetRelays(self)
     |      Returns the cached status of the relays as a bitmask.
     |  
     |  IsRelayClosed(self, relay)
     |      Returns the status of a relay.
     |      
     |      Args:
     |        relay: int, 1 - 4, the relay to enable. Note that olimex
     |          mod-io has exactly 4 relays.
     |      
     |      Raises:
     |        ValueError if an invalid relay number is passed.
     |      
     |      Returns:
     |        False if the releay is opened, True if closed.
     |  
     |  OpenContactRelay(self, relay)
     |      OpenContact a specific relay.
     |      
     |      Args:
     |        relay: int, 1 - 4, the relay to enable. Note that olimex
     |          mod-io has exactly 4 relays.
     |      
     |      Raises:
     |        ValueError if an invalid relay number is passed.
     |  
     |  ReadAin(self, ain)
     |      Reads an analog input, and returns its value.
     |      
     |      Args:
     |        ain: integer, the number of the analogic input to read.
     |            On mod-io, analg inputs are numbered 1 - 4.
     |      
     |      Raises:
     |        ValueError: if an invalid analog input is passed.
     |      
     |      Returns:
     |        integer, the value of the analog input. Note that mod-io
     |        analog inputs have a precision of 10 bits.
     |  
     |  ReadRelay(self, relay_out)
     |      Return value for relay 
     |      
     |      Args:
     |        relay_out: int, 1 - 4, the relay value to get for.
     |          Note that olimex mod-io has exactly 4 relays
     |      
     |      Raises:
     |        ValueError if an invalid relay number is passed.
     |      
     |      Returns:
     |        False if the relay is low, True if high.
     |  
     |  ReadRelays(self)
     |      Reads the status of the relays from the board, and returns it.
     |  
     |  SetRelays(self, value)
     |      Set and return the relay status.
     |  
     |  __init__(self, address=88, bus=1, communicator=<class 'modio.SmbBus'>)
     |      Constructs a device object.
     |      
     |      Args:
     |        address: integer, mod-io address.
     |        bus: integer, SMB bus to use to communicate with mod-io.
     |        communicator: SmbBus or FakeBus, for testing purposes.
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors defined here:
     |  
     |  __dict__
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__
     |      list of weak references to the object (if defined)
     |  
     |  ----------------------------------------------------------------------
     |  Data and other attributes defined here:
     |  
     |  AIN_READ_COMMAND = 48
     |  
     |  CHANGE_ADDRESS_COMMAND = 240
     |  
     |  DEFAULT_ADDRESS = 88
     |  
     |  DEFAULT_BUS = 1
     |  
     |  DIGITAL_IN_COMMAND = 32
     |  
     |  RELAY_READ_COMMAND = 64
     |  
     |  RELAY_WRITE_COMMAND = 16
    
    class DeviceNotFoundException(exceptions.IOError)
     |  Raised if we cannot communicate with the device.
     |  
     |  Method resolution order:
     |      DeviceNotFoundException
     |      exceptions.IOError
     |      exceptions.EnvironmentError
     |      exceptions.StandardError
     |      exceptions.Exception
     |      exceptions.BaseException
     |      __builtin__.object
     |  
     |  Data descriptors defined here:
     |  
     |  __weakref__
     |      list of weak references to the object (if defined)
     |  
     |  ----------------------------------------------------------------------
     |  Methods inherited from exceptions.IOError:
     |  
     |  __init__(...)
     |      x.__init__(...) initializes x; see help(type(x)) for signature
     |  
     |  ----------------------------------------------------------------------
     |  Data and other attributes inherited from exceptions.IOError:
     |  
     |  __new__ = <built-in method __new__ of type object>
     |      T.__new__(S, ...) -> a new object with type S, a subtype of T
     |  
     |  ----------------------------------------------------------------------
     |  Methods inherited from exceptions.EnvironmentError:
     |  
     |  __reduce__(...)
     |  
     |  __str__(...)
     |      x.__str__() <==> str(x)
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors inherited from exceptions.EnvironmentError:
     |  
     |  errno
     |      exception errno
     |  
     |  filename
     |      exception filename
     |  
     |  strerror
     |      exception strerror
     |  
     |  ----------------------------------------------------------------------
     |  Methods inherited from exceptions.BaseException:
     |  
     |  __delattr__(...)
     |      x.__delattr__('name') <==> del x.name
     |  
     |  __getattribute__(...)
     |      x.__getattribute__('name') <==> x.name
     |  
     |  __getitem__(...)
     |      x.__getitem__(y) <==> x[y]
     |  
     |  __getslice__(...)
     |      x.__getslice__(i, j) <==> x[i:j]
     |      
     |      Use of negative indices is not supported.
     |  
     |  __repr__(...)
     |      x.__repr__() <==> repr(x)
     |  
     |  __setattr__(...)
     |      x.__setattr__('name', value) <==> x.name = value
     |  
     |  __setstate__(...)
     |  
     |  __unicode__(...)
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors inherited from exceptions.BaseException:
     |  
     |  __dict__
     |  
     |  args
     |  
     |  message
    
    class DigitalIn(__builtin__.object)
     |  Represents a single digital in, convenience wrapper around the device class.
     |  
     |  Methods defined here:
     |  
     |  Get(self)
     |      Get status of this digital in.
     |  
     |  __init__(self, device, number)
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors defined here:
     |  
     |  __dict__
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__
     |      list of weak references to the object (if defined)
    
    class FakeBus(__builtin__.object)
     |  Emulates a SmbBus for testing purposes.
     |  
     |  Attributes:
     |    address: integer, the address where mod-io can be found.
     |  
     |  Methods defined here:
     |  
     |  Write(self, key, value)
     |  
     |  __init__(self, bus, address)
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors defined here:
     |  
     |  __dict__
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__
     |      list of weak references to the object (if defined)
    
    class Relay(__builtin__.object)
     |  Represents a single relay, convenience wrapper around the device class.
     |  
     |  Methods defined here:
     |  
     |  CloseContact(self)
     |      Enables this relay, by closing the contact.
     |  
     |  Get(self)
     |      Deprecated, use IsClosed instead.
     |  
     |  IsClosed(self)
     |      Returns true if this relay is closed, false otherwise.
     |  
     |  OpenContact(self)
     |      Disables this relay, by opening the contact.
     |  
     |  __init__(self, device, number)
     |      Creates a new Relay instance.
     |      
     |      Args:
     |        device: a Device instance, something like modio.Device().
     |        number: int, the number of the relay to control, from 1 to 4.
     |      
     |      Raises:
     |        ValueError, if the number is invalid.
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors defined here:
     |  
     |  __dict__
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__
     |      list of weak references to the object (if defined)
    
    class SMBBusNotConfiguredProperly(exceptions.IOError)
     |  Raised if we can't find the propber smbbus setup.
     |  
     |  Method resolution order:
     |      SMBBusNotConfiguredProperly
     |      exceptions.IOError
     |      exceptions.EnvironmentError
     |      exceptions.StandardError
     |      exceptions.Exception
     |      exceptions.BaseException
     |      __builtin__.object
     |  
     |  Data descriptors defined here:
     |  
     |  __weakref__
     |      list of weak references to the object (if defined)
     |  
     |  ----------------------------------------------------------------------
     |  Methods inherited from exceptions.IOError:
     |  
     |  __init__(...)
     |      x.__init__(...) initializes x; see help(type(x)) for signature
     |  
     |  ----------------------------------------------------------------------
     |  Data and other attributes inherited from exceptions.IOError:
     |  
     |  __new__ = <built-in method __new__ of type object>
     |      T.__new__(S, ...) -> a new object with type S, a subtype of T
     |  
     |  ----------------------------------------------------------------------
     |  Methods inherited from exceptions.EnvironmentError:
     |  
     |  __reduce__(...)
     |  
     |  __str__(...)
     |      x.__str__() <==> str(x)
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors inherited from exceptions.EnvironmentError:
     |  
     |  errno
     |      exception errno
     |  
     |  filename
     |      exception filename
     |  
     |  strerror
     |      exception strerror
     |  
     |  ----------------------------------------------------------------------
     |  Methods inherited from exceptions.BaseException:
     |  
     |  __delattr__(...)
     |      x.__delattr__('name') <==> del x.name
     |  
     |  __getattribute__(...)
     |      x.__getattribute__('name') <==> x.name
     |  
     |  __getitem__(...)
     |      x.__getitem__(y) <==> x[y]
     |  
     |  __getslice__(...)
     |      x.__getslice__(i, j) <==> x[i:j]
     |      
     |      Use of negative indices is not supported.
     |  
     |  __repr__(...)
     |      x.__repr__() <==> repr(x)
     |  
     |  __setattr__(...)
     |      x.__setattr__('name', value) <==> x.name = value
     |  
     |  __setstate__(...)
     |  
     |  __unicode__(...)
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors inherited from exceptions.BaseException:
     |  
     |  __dict__
     |  
     |  args
     |  
     |  message
    
    class SmbBus(__builtin__.object)
     |  Represent an SMB bus to read / write from modio.
     |  
     |  Attributes:
     |    address: integer, the address where mod-io can be found.
     |  
     |  Methods defined here:
     |  
     |  ReadBlock(self, key, length)
     |      Reads a block from olimex mod-io.
     |      
     |      Args:
     |        key: integer, an address where to read data from.
     |        length: integer, how much data to read.
     |  
     |  Write(self, key, value)
     |      Sends a request to olimex mod-io.
     |      
     |      Args:
     |        key: integer, an address where to write data.
     |        value: string, the data to write.
     |  
     |  __init__(self, bus, address)
     |      Instantiates a SmbBus.
     |      
     |      Args:
     |        bus: integer, bus number, generally 0 or 1.
     |        address: integer, generally 0x58, the address where
     |          mod-io can be found.
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors defined here:
     |  
     |  __dict__
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__
     |      list of weak references to the object (if defined)

FUNCTIONS
    HandleReadAin(args)
    
    HandleRelay(args)
    
    PrintHelp(message)
    
    main(args)
        Provides access to mod-io from the command line.
        
        Commands:
          relay    - to change the state of a relay.
            close NUMBER - closes the specified relay.
            open NUMBER - opens the specified relay.
        
          read-ain - to read an analog input.
            read-ain NUMBER - reads the value from the specified ain.
        
        Examples:
          # Close the contact on relay 1.
          modio.py relay close 1
          # Open the contact on relay 1.
          modio.py relay open 1
        
          # Read the first analog input.
          modio.py read-ain 1
          57