examples: Cleanup Python examples

Signed-off-by: Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
Signed-off-by: Brendan Le Foll <brendan.le.foll@intel.com>

examples/python/aio.py

@@ -21,14 +21,21 @@
 # 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.
+#
+# Example Usage: Reads integer and float value from ADC
 
 import mraa
 
 print(mraa.getVersion())
 
 try:
+    # initialise AIO
     x = mraa.Aio(0)
+
+    # read integer value
     print(x.read())
+
+    # read float value
     print("%.5f" % x.readFloat())
 except:
     print("Are you sure you have an ADC?")

examples/python/gpio.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python
+
+# Author: Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
+# Copyright (c) 2018 Linaro Ltd.
+#
+# 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.
+#
+# Example Usage: Toggles GPIO 23 and 24 continuously in an alternative pattern
+
+import mraa
+import time
+
+# initialise gpio 23
+gpio_1 = mraa.Gpio(23)
+
+# initialise gpio 24
+gpio_2 = mraa.Gpio(24)
+
+# set gpio 23 to output
+gpio_1.dir(mraa.DIR_OUT)
+
+# set gpio 24 to output
+gpio_2.dir(mraa.DIR_OUT)
+
+# toggle both gpio's
+while True:
+    gpio_1.write(1)
+    gpio_2.write(0)
+
+    time.sleep(1)
+
+    gpio_1.write(0)
+    gpio_2.write(1)
+
+    time.sleep(1)

examples/python/gpio_advanced.py

@@ -21,6 +21,8 @@
 # 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
+#
+# Example Usage: Triggers ISR upon GPIO state change
 
 import mraa
 import time
@@ -33,21 +35,24 @@ c = Counter()
 
 # inside a python interrupt you cannot use 'basic' types so you'll need to use
 # objects
-def test(gpio):
+def isr_routine(gpio):
     print("pin " + repr(gpio.getPin(True)) + " = " + repr(gpio.read()))
     c.count += 1
 
+# GPIO
 pin = 6;
-if (len(sys.argv) == 2):
-  try:
-    pin = int(sys.argv[1], 10)
-  except ValueError:
-    printf("Invalid pin " + sys.argv[1])
+
 try:
+    # initialise GPIO
     x = mraa.Gpio(pin)
+
     print("Starting ISR for pin " + repr(pin))
+
+    # set direction and edge types for interrupt
     x.dir(mraa.DIR_IN)
-	x.isr(mraa.EDGE_BOTH, test, x)
+    x.isr(mraa.EDGE_BOTH, isr_routine, x)
+
+    # wait until ENTER is pressed
     var = raw_input("Press ENTER to stop")
     x.isrExit()
 except ValueError as e:

examples/python/hello_gpio.py

@@ -1,30 +0,0 @@
-#!/usr/bin/env python
-
-# Author: Thomas Ingleby <thomas.c.ingleby@intel.com>
-# Copyright (c) 2014 Intel Corporation.
-#
-# 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.
-
-import mraa
-
-print (mraa.getVersion())
-x = mraa.Gpio(13)
-x.dir(mraa.DIR_OUT)
-x.write(1)

examples/python/i2c_bmp85.py

@@ -21,12 +21,13 @@
 # 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
+#
+# Example Usage: Shows the 'advanced' i2c functionality from python i2c
+#                read/write
 
 import mraa as m
 
-# this example will show the 'advanced' i2c functionality from python i2c
-# read/write
-
+# initialise I2C
 x = m.I2c(0)
 x.address(0x77)
 

examples/python/i2c_rgb.py

@@ -21,11 +21,12 @@
 # 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
+#
+# Example Usage: Changes the Grove-LCD RGB backlight to a nice shade of purple
 
 import mraa
 
-# This example will change the LCD backlight on the Grove-LCD RGB backlight
-# to a nice shade of purple
+# initialise I2C
 x = mraa.I2c(0)
 x.address(0x62)
 
@@ -33,7 +34,7 @@ x.address(0x62)
 x.writeReg(0, 0)
 x.writeReg(1, 0)
 
-# sent RGB color data
+# write RGB color data
 x.writeReg(0x08, 0xAA)
 x.writeReg(0x04, 255)
 x.writeReg(0x02, 255)

examples/python/led.py

@@ -0,0 +1,55 @@
+#!/usr/bin/env python
+
+# Author: Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
+# Copyright (c) 2018 Linaro Ltd.
+#
+# 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.
+#
+# Example Usage: Reads maximum brightness value for user1 led and turns it
+#                on/off depending on current state. Then sets led trigger
+#                to heartbeat
+
+import mraa
+import time
+
+# initialise user1 led
+led_1 = mraa.Led("user1")
+
+# read maximum brightness
+val = led_1.readMaxBrightness()
+
+print("maximum brightness value for user1 led is: %d" % val);
+
+# turn led on/off depending on read max_brightness value
+if (val >= 1):
+    val = 0
+# never reached mostly
+else:
+    val = 1
+
+# set LED brightness
+led_1.setBrightness(val)
+
+# sleep for 5 seconds
+time.sleep(5)
+
+led_1.trigger("heartbeat")
+
+print("led trigger set to: heartbeat")

examples/python/pwm.py

@@ -21,18 +21,29 @@
 # 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.
+#
+# Example Usage: Generates PWM at a step rate of 0.01 continuously.
 
 import mraa
 import time
 
+# initialise PWM
 x = mraa.Pwm(3)
+
+# set PWM period
 x.period_us(700)
+
+# enable PWM
 x.enable(True)
+
 value= 0.0
 
 while True:
+    # write PWM value
     x.write(value)
+
     time.sleep(0.05)
+
     value = value + 0.01
     if value >= 1:
         value = 0.0

examples/python/spi.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 
-# Author: Brendan Le Foll <brendan.le.foll@intel.com>
-# Copyright (c) 2015 Intel Corporation.
+# Author: Henry Bruce <henry.bruce@intel.com>
+# Copyright (c) 2016 Intel Corporation.
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -22,21 +22,24 @@
 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE
 
-import mraa as m
-import random as rand
+# Example Usage: Read from MCP3004 ADC pin 0 in single ended mode
 
-# Excuse the super boring example, I was out of fun devices to play with, this
-# will write and read the same data back to itself, a few 100 times, just short
-# MISO & MOSI on your board
+import mraa
+import time
 
-dev = m.Spi(0)
+# initialise SPI
+dev = mraa.Spi(0)
 
-for x in range(0,100):
-  txbuf = bytearray(4)
-  for y in range(0,4):
-    txbuf[y] = rand.randrange(0, 256)
+# prepare data to send
+txbuf = bytearray(3)
+txbuf[0] = 0x01
+txbuf[1] = 0x80
+txbuf[2] = 0x00
+
+while True:
+    # send data through SPI
     rxbuf = dev.write(txbuf)
-  if rxbuf != txbuf:
-    print("We have an error captain!")
-    exit(1)
+    value = ((rxbuf[1] & 0x03) << 8) | rxbuf[2]
+    print(value)
 
+    time.sleep(0.5)

examples/python/spi_loopback.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 
-# Author: Henry Bruce <henry.bruce@intel.com>
-# Copyright (c) 2016 Intel Corporation.
+# Author: Brendan Le Foll <brendan.le.foll@intel.com>
+# Copyright (c) 2015 Intel Corporation.
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -21,20 +21,22 @@
 # 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
+#
+# Example Usage: Loopbacks data between MISO and MOSI 100 times
 
-# Read from MCP3004 ADC pin 0 in single ended mode
-import mraa
-import time
+import mraa as m
+import random as rand
 
-dev = mraa.Spi(0)
-txbuf = bytearray(3)
-txbuf[0] = 0x01
-txbuf[1] = 0x80
-txbuf[2] = 0x00
+# intialise SPI
+dev = m.Spi(0)
 
-while True:
+for x in range(0,100):
+    txbuf = bytearray(4)
+    for y in range(0,4):
+        txbuf[y] = rand.randrange(0, 256)
+
+    # send and receive data through SPI
     rxbuf = dev.write(txbuf)
-    value = ((rxbuf[1] & 0x03) << 8) | rxbuf[2]
-    print(value)
-    time.sleep(0.5)
-
+    if rxbuf != txbuf:
+        print("Data mismatch!")
+        exit(1)

examples/python/uart.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 
-# Author: Thomas Ingleby <thomas.c.ingleby@intel.com>
-# Copyright (c) 2014 Intel Corporation.
+# Author: Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
+# Copyright (c) 2018 Linaro Ltd.
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -21,15 +21,20 @@
 # 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.
+#
+# Example Usage: Sends data through UART
 
 import mraa
 import time
+import sys
 
-x = mraa.Gpio(8)
-x.dir(mraa.DIR_OUT)
+# serial port
+port = "/dev/ttyACM0"
 
-while True:
-    x.write(1)
-    time.sleep(0.2)
-    x.write(0)
-    time.sleep(0.2)
+data = 'Hello Mraa!'
+
+# initialise UART
+uart = mraa.Uart(port)
+
+# send data through UART
+uart.write(bytearray(data, 'utf-8'))

examples/python/uart_receiver.py

@@ -21,10 +21,13 @@
 # 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
+#
+# Example Usage: Expects 'X' flag from the sender. This example requires
+#                `uart_sender.py` to be running on the other end.
 
 import mraa
 
-# Initialize UART
+# Initialise UART
 u = mraa.Uart(0)
 
 # Set UART parameters
@@ -39,6 +42,7 @@ while True:
         # We are doing 1-byte reads here
         data_byte = u.readStr(1)
         print(data_byte)
+
         # Just a two-way half-duplex communication example, "X" is a flag
         if data_byte == "X":
             u.writeStr("Yes, master!")

examples/python/uart_sender.py

@@ -21,6 +21,11 @@
 # 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
+#
+# Example Usage: Sends some info messages in the form of bytearray and strings
+#                along with `X` flag and prints the response from other end.
+#                This example requires uart_receiver.py to be running on the
+#                other end.
 
 import mraa
 import sys

src/python/python2/docs/example.rst

@@ -12,7 +12,7 @@ Hello GPIO
 
 Here is the simplest Gpio program in mraa.
 
-.. literalinclude:: ../../../../examples/python/hello_gpio.py
+.. literalinclude:: ../../../../examples/python/gpio.py
   :prepend: import mraa
   :start-after: import mraa
 
@@ -27,7 +27,7 @@ values.
 
 **Note:** Galileo Gen1 only supports EDGE_BOTH
 
-.. literalinclude:: ../../../../examples/python/hello_isr.py
+.. literalinclude:: ../../../../examples/python/gpio_advanced.py
   :prepend: import mraa
   :start-after: import mraa
 
@@ -44,7 +44,7 @@ The I2c module module has a number of different ways of interacting with the
 i2c bus, including a number of overloaded read() calls and the writeReg()
 helper function.
 
-.. literalinclude:: ../../../../examples/python/bmp85.py
+.. literalinclude:: ../../../../examples/python/i2c_bmp85.py
   :prepend: x = m.I2c(0)
   :start-after: x = m.I2c(0)
 
@@ -56,7 +56,7 @@ Pwm
 The PWM module is rather simple, note that different hardware support PWM
 generation is various different ways so results may vary.
 
-.. literalinclude:: ../../../../examples/python/cycle-pwm3.py
+.. literalinclude:: ../../../../examples/python/pwm.py
   :prepend: import mraa
   :start-after: import mraa
 
@@ -91,3 +91,13 @@ Receiver:
 .. literalinclude:: ../../../../examples/python/uart_receiver.py
   :prepend: import mraa
   :start-after: import mraa
+
+LED
+===
+
+LED module is used for controlling the on-board LEDs. With the
+help of this module, we can control the brightness, trigger etc...
+
+.. literalinclude:: ../../../../examples/python/led.py
+  :prepend: import mraa
+  :start-after: import mraa