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())
+print(mraa.getVersion())
 
 try:
+    # initialise AIO
     x = mraa.Aio(0)
-    print (x.read())
-    print ("%.5f" % x.readFloat())
+
+    # read integer value
+    print(x.read())
+
+    # read float value
+    print("%.5f" % x.readFloat())
 except:
-    print ("Are you sure you have an ADC?")
+    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,34 +21,39 @@
 # 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
 import sys
 
 class Counter:
-  count = 0
+    count = 0
 
 c = Counter()
 
 # inside a python interrupt you cannot use 'basic' types so you'll need to use
 # objects
-def test(gpio):
-  print("pin " + repr(gpio.getPin(True)) + " = " + repr(gpio.read()))
-  c.count+=1
+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:
-	x = mraa.Gpio(pin)
-	print("Starting ISR for pin " + repr(pin))
-	x.dir(mraa.DIR_IN)
-	x.isr(mraa.EDGE_BOTH, test, x)
-	var = raw_input("Press ENTER to stop")
-	x.isrExit()
+    # 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, isr_routine, x)
+
+    # wait until ENTER is pressed
+    var = raw_input("Press ENTER to stop")
+    x.isrExit()
 except ValueError as e:
     print(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,18 +21,19 @@
 # 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)
 
 # initialise device
 if x.readReg(0xd0) != 0x55:
-  print("error")
+    print("error")
 
 # we want to read temperature so write 0x2e into control reg
 x.writeReg(0xf4, 0x2e)

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)
-  rxbuf = dev.write(txbuf)
-  if rxbuf != txbuf:
-    print("We have an error captain!")
-    exit(1)
+# 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)
+    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,11 +21,14 @@
 # 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
-u=mraa.Uart(0)
+# Initialise UART
+u = mraa.Uart(0)
 
 # Set UART parameters
 u.setBaudRate(115200)
@@ -35,10 +38,11 @@ u.setFlowcontrol(False, False)
 # Start a neverending loop waiting for data to arrive.
 # Press Ctrl+C to get out of it.
 while True:
-  if u.dataAvailable():
-    # 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!")
+    if u.dataAvailable():
+        # 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,12 +21,17 @@
 # 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
 
 sys.stdout.write("Initializing UART...")
-u=mraa.Uart(0)
+u = mraa.Uart(0)
 print("...done")
 
 print("Setting UART parameters: baudrate 115200, 8N1, no flow control")
@@ -52,6 +57,6 @@ u.writeStr("X")
 print("...sent, awaiting response...")
 # Checking for data in the RX buffer, giving it a 100ms timeout
 if u.dataAvailable(100):
-  print("We've got a response: '{0}', says the other side".format(u.readStr(20)))
+    print("We've got a response: '{0}', says the other side".format(u.readStr(20)))
 else:
-  print("No data received, do you have anything at the other end?")
+    print("No data received, do you have anything at the other end?")