MICILE EZ_Arduino Documentation
version: 0.9
A few notes about our documentation:
  • The intentions of this documentation are to keep things simple.
  • Please see the examples at the end of each section for concrete examples of how to use each function.
  • If in doubt how to use a function, experiment!
  • We don't believe in writing more words just to make the documentation look more substantial
  • Quick Reference
    Function List
    Compatible Devices
    Arduino Uno Board

    * Please contact us for information on adding support for a device.

    Note! You must install the MICILE_Arduino_Uno_Sketch on the Aruduino before using the EZ_Arduino Library.

    The sketch can be downloaded by clicking the link below.

    Micile Arduino Uno Sketch v1.0

    Please refere to the official Arduino documentation for instructions on how to upload a sketch to an Arduino Uno.
    Arduino Functions
    Note! This library is experimental and may cause tablets to crash or lockup. Please report any issues to info@micile.com so we can investigate them.

    Hot plugging and unplugging the Arduino board to the usb connector of a tablet is not recommended and may cause the table to lock up due to the ACM driver crashing.


    arduino_init(board_type = ARDUINO_BOARD_UNO, serial_port_name = '/dev/ttyACM0')
    Initializes the ez_arduino library. This should be called before any other ez_arduino library functions are called.

    The board_type parameter is optional and defaults to the ARDUINO_BOARD_UNO value for an Arduino Uno board. Currently no other boards are supported other than the Arduino Uno.

    The serial_port_name parameter is optional and defaults to the value of '/dev/ttyACM0' which is the default port of an Arduino Uno.
    arduino_configure_pin(pin, pin_config, initial_value = None)
    Configures a pin to be of a specific function. Not all pins can be all functions. Please see the table below for a list of pins and valid functions for those pins.

    For the Arduino Uno board, the available pin values are: PIN_2, PIN_3, PIN_4, PIN_5, PIN_6, PIN_7, PIN_8, PIN_9, PIN_10, PIN_11, PIN_12, PIN_13, PIN_A0, PIN_A1, PIN_A2, PIN_A3, PIN_A4, PIN_A5

    The available pin_config values are PIN_INPUT, PIN_INPUT_PULLUP, PIN_OUTPUT, PIN_ADC, PIN_PWM, and PIN_SPECIAL

    The chart below shows what pin_configs are allowed for which Arduino pin.

    The application should always explicitely set the function of any pins it intends to use.

    The SPECIAL FUNCTION column shows which pins are overriden when special functions such as the I2C / TWI bus and SPI bus are activated.
    The pins used by the I2C / TWI and SPI bus must be set to PIN_SPECIAL before enabling the bus.

    If the pin_config parameter is PIN_OUTPUT, an initial value can be set through the initial_value parameter. Valid values for initial_value are True and False.
    A True value will set the initial value as pin HIGH, and a False value will set the initial pin value to LOW.

    Arduino Uno
    Pin NamePIN_INPUTPIN_INPUT_PULLUPPIN_OUTPUTPIN_ADCPIN_PWMPIN_SPECIALSPECIAL FUNCTION
    PIN_2 X D
    PIN_3 D X
    PIN_4 X D
    PIN_5 D X
    PIN_6 D X
    PIN_7 X D
    PIN_8 X D
    PIN_9 D X
    PIN_10 D X X SPI_SS
    PIN_11 D X X SPI_MOSI
    PIN_12 X D X SPI_MISO
    PIN_13 D X SPI_SCK / LED
    PIN_A0 X X D
    PIN_A1 X X D
    PIN_A2 X X D
    PIN_A3 X X D
    PIN_A4 X X D X I2C_SDA / TWI_SDA
    PIN_A5 X X D X I2C_SDA / TWI_SDL

    Advanced users can remove the restrictions placed on which pins can be configured for PIN_INPUT and PIN_OUTPUT by modifying the supplied Arduino Sketch. As with any microcontroller, be sure to double check all connections are correct and to the intended pins before turning on the microcontroller board to ensure that damage does not occur to the microcontroller board or any accessory boards that are attached.
    arduino_enable_i2c(enable)
    Enables or disables the I2C / TWI (Two Wire Interface) bus functionality on the Arduino Board.

    The I2C SDA Pin and I2C SDL Pin must be configured as PIN_SPECIAL before enabling the I2C / TWI Bus.

    If the enable parameter is True, then the I2C bus will be enabled. if the enable parameter is False, the I2C bus will be disabled.

    When the I2C bus is enabled, the SDA and SDL pins of the I2C bus can only be used for I2C communication and can not be used as general purpose IO pins.

    The chart below shows which pins should be used for the I2C SDA and SDL pins.

    Board Name I2C SDA PinI2C SDL Pin
    Arduino UnoA4 A5
    arduino_enable_spi(enable, spi_mode = SPI_MODE0, bit_order = SPI_MSB, clock_divisor = 128)
    Enables or disables the SPI bus functionality on the Arduino Board.

    The SPI Pin, SPI MOSI Pin, SPI_MISO Pin, and SPI _SCK Pin must be configured as PIN_SPECIAL before enabling the SPI Bus.

    If the enable parameter is True, then the SPI bus will be enabled. if the enable parameter is False, the SPI bus will be disabled.

    Please see the official Arduino documentation for more information on SPI modes, bit orders, and clock divisors.

    The spi_mode parameter sets the SPI mode. Valid values are SPI_MODE0, SPI_MODE1, SPI_MODE2, SPI_MODE3. THe default is Mode 0, which will usually work with most devices.

    The bit_order parameter sets the SPI bit mode. Valid values are SPI_MSB and SPI_LSB. The default is SPI_MSB which will usually work with most devices.

    The clock_divisor parameter sets the SPI clock divisor. Valid values are 2, 4, 8, 16, 32, 64, and 128. The default is 128 which will usually work with most devices.

    When the SPI bus is enabled, the MOSI, MISO, and SCK can only be used for SPI communication and can not be used as general purpose IO pins.

    The chart below shows which pins should be used for the SPI SS, MOSI, MISO, and SCK pins

    Board Name SPI MOSI PinSPI MISO PinSPI SCK Pin
    Arduino UnoPIN_11 PIN_12 PIN_13
    arduino_read_adc(pin)
    Reads the value of a pin previously configured as a PIN_ADC pin by the arduino_configure_pin function.

    The pin parameter can be any of the pins described in the arduino_configure_pin function capable of PIN_ADC functionality.

    The Arduino contains a 10 bit ADC (Analog to Digital Converter), so values returned will be in the range of 0 to 1023.
    arduino_read_i2c_bus(address, register, num_bytes)
    Reads data from the I2C / TWI bus using standard register format.

    First the value in the register parameter will be written to the I2C address specified in the address parameter and then the number of bytes specified in the num_bytes parameter will be read from the I2C bus.

    The I2C / TWI bus must first be enabled with a call to the arduino_enable_i2c function before this function can be called.

    The data returned will be encoded in an ascii string. See the code examples below for how to extract byte data from a string using the ord function.
    arduino_read_pin(pin)
    Reads the value of a pin previously configured as a PIN_INPUT pin by the arduino_configure_pin function.

    The pin parameter can be any of the pins described in the arduino_configure_pin function capable of PIN_INPUT functionality.

    Returns True if the pin is high, or False if the pin is low.
    arduino_readwrite_spi_bus(buffer, cs_pin = None)
    Writes the contents of the buffer to the SPI bus.

    A pin can be specified in the cs_pin parameter to act as an automatic chip select pin. If a pin is specified, it must be already configured as a PIN_OUTPUT and its value
    will be set to LOW before the SPI transmission and then brought back to HIGH.

    Because of the inherent way that the SPI bus operates, the same number of bytes contained in the buffer will also be read in from the SPI bus and returned.

    The SPI bus must first be enabled with a call to the arduino_enable_spi function before this function can be called.

    The data passed in the buffer parameter must be encoded in an ascii string. See the code examples below for how to encode byte literal values in a string using \x00 notation and the chr function.
    The data returned will be encoded in an ascii string. See the code examples below for how to extract byte data from a string using the ord function.
    arduino_set_pwm(pin, duty_cycle)
    Changes the frequency and duty cycle of a a pin previosly configures as a PIN_PWM pin by the arduino_configure_pin function.

    The Arduino PWM has a fixed frequency of approximately 490Hz.

    The duty_cycle parameter specifies the new duty cycle as a floating point number between 0.0 and 1.0. For example, a value of 0.25 would specify a duty cycle of 25%.
    arduino_write_i2c_bus(address, register, buffer)
    Writes data to the I2C / TWI bus using standard register format.

    First the value in the register parameter will be written to the I2C address specified in the address parameter and then the contents of the buffer parameter will be written to the I2C bus.

    The I2C / TWI bus must first be enabled with a call to the arduino_enable_i2c function before this function can be called.
    The data passed in the buffer parameter must be encoded in an ascii string. See the code examples below for how to encode byte literal values in a string using \x00 notation and the chr function.
    arduino_write_pin(pin, value)
    Writes a new value to a pin previously configured as a PIN_OUTPUT pin by the arduino_configure_pin function.

    The pin parameter can be any of the pins described in the arduino_configure_pin function capable of PIN_OUTPUT functionality.

    If value is True, the output value of the pin will be set to High. If value is False, the output value of the pin will be set to low.
    # --------------------------------------------------
    # Arduino_LED_demo.py
    # --------------------------------------------------
     
    # Makes the LED blink
     
    # import the ez_arduino libary v0.9 and the time library
    from ez_arduino_09 import * 
    import time
     
    # Initialize the Arduino
    arduino_init()
     
    # Pin 13 on an Arduino Uno is connected to its onboard LED
    # Set Pin 13 to be an output pin
    arduino_configure_pin(PIN_13PIN_OUTPUT)
     
    # Loop forever
    while True:
        # Turn the LED on, wait 0.5 second, turn the LED off, wait 0.5 second
        arduino_write_pin(PIN_13True)
        time.sleep(0.5)
        arduino_write_pin(PIN_13False)
        time.sleep(0.5)


    # --------------------------------------------------
    # Arduino_Switch_demo.py
    # --------------------------------------------------
     
    # Makes the LED follow a switch connected to PIN_2 
     
    # import the ez_arduino libary v0.9 and the time library
    from ez_arduino_09 import * 
    import time
     
    # Initialize the Arduino
    arduino_init()
     
    # connect a switch wired to ground on Pin 2
    # Set Pin 2 to be an input pin with pullup enabled
    arduino_configure_pin(PIN_2PIN_INPUT_PULLUP)
     
    # Pin 13 on an Arduino Uno is connected to its onboard LED
    # Set Pin 13 to be an output pin
    arduino_configure_pin(PIN_13PIN_OUTPUT)
     
    # Loop forever
    while True:
        # Read the Switch and set the LED state to follow that of the switch
        val = arduino_read_pin(PIN_2)
        arduino_write_pin(PIN_13val)
        
        # sleep so app will stop when interrupted by the IDE
        time.sleep(0.01)


    # --------------------------------------------------
    # Arduino_ADC_demo.py
    # --------------------------------------------------
     
    # Shows how to use the Arduino ADC
     
    # import the ez_arduino libary v0.9 and the time library
    from ez_arduino_09 import * 
    import time
     
    # Initialize the Arduino
    arduino_init()
     
    # Configure Pins for an SPI device
    arduino_configure_pin(PIN_A0PIN_ADC)
     
    # Make the digital pot run through its range
    while True:
        # Read the ADC and just print the value to the debug window
        val = arduino_read_adc(PIN_A0)
        print val
        
        # sleep so app will stop when interrupted by the IDE
        time.sleep(0.01)


    # --------------------------------------------------
    # Arduino_SPI_demo.py
    # --------------------------------------------------
     
    # Shows how to use the SPI functions with an MCP41010 Digital Potentiometer
     
    # import the ez_arduino libary v0.9 and the time library
    from ez_arduino_09 import * 
    import time
     
    # Initialize the Arduino
    arduino_init()
     
    # Configure Pins for an SPI device
    arduino_configure_pin(PIN_11PIN_SPECIAL)
    arduino_configure_pin(PIN_12PIN_SPECIAL)
    arduino_configure_pin(PIN_13PIN_SPECIAL)
    arduino_configure_pin(PIN_9PIN_OUTPUT) # chip select of SPI device
     
    # Enable the SPI bus
    arduino_enable_spi(True)
     
    # Make the digital pot run through its range
    while True:
        for i in range(0255):
            # Send the SPI command (see MCP41010 datasheet for details)
            cmd = "\x11" + chr(i)   # send 0x11 followed by potentiometer value
            arduino_readwrite_spi_bus(cmdPIN_9)
            
            # sleep so app will stop when interrupted by the IDE
            time.sleep(0.01)


    # --------------------------------------------------
    # Arduino_PWM_demo.py
    # --------------------------------------------------
     
    # Shows how to use the Arduino PWM
     
    # import the ez_arduino libary v0.9 and the time library
    from ez_arduino_09 import * 
    import time
     
    # Initialize the Arduino
    arduino_init()
     
    # Configure Pins for an SPI device
    arduino_configure_pin(PIN_9PIN_PWM)
     
    # Configure for a 25% duty cycle
    arduino_set_pwm(PIN_90.25)
     
    # Loop forever
    while True:
        # sleep so app will stop when interrupted by the IDE
        time.sleep(0.01)


    # --------------------------------------------------
    # Arduino_I2C_demo.py
    # --------------------------------------------------
     
    # Shows how to use the Arduino I2C to communicate with the
    # LSM303DLMTR Tilt Compensated Compass
     
    # import the ez_arduino libary v0.9 and the time library
    from ez_arduino_09 import * 
    import time
     
    # Initialize the Arduino
    arduino_init()
     
    # Configure Pins for an I2C device
    arduino_configure_pin(PIN_A4PIN_SPECIAL)
    arduino_configure_pin(PIN_A5PIN_SPECIAL)
     
    # Enable the I2C Bus
    arduino_enable_i2c(True)
     
    # Dump the registers to the debug window just to see
    for i in range(016):
        val = arduino_read_i2c_bus(0x1Ei1)
        print "Register 0x%02X = 0x%02X" % (iord(val[0]))
        
    # Switch sensor to continuous conversion mode
    arduino_write_i2c_bus(0x1E0x02chr(0x00))
     
    # Loop and print the compass values
    while True:
        # read the registers (See LSM303DLM datasheet for details)
        val_x = arduino_read_i2c_bus(0x1E0x032)
        val_y = arduino_read_i2c_bus(0x1E0x052)
        val_z = arduino_read_i2c_bus(0x1E0x072)
        x = ord(val_x[0]) * 256 + ord(val_x[1])
        y = ord(val_y[0]) * 256 + ord(val_y[1])
        z = ord(val_z[0]) * 256 + ord(val_z[1])
        
        # print the magnetic compass values
        print "%04X %04X %04X" % (xyz)
        
        # sleep so app will stop when interrupted by the IDE
        time.sleep(0.01)