diff --git a/docs/src/files/serial_test.py b/docs/src/files/serial_test.py new file mode 100644 index 0000000000000000000000000000000000000000..4f55b0b31ad3fbdb176db5322faff0220d0b1e6f --- /dev/null +++ b/docs/src/files/serial_test.py @@ -0,0 +1,47 @@ +#!/usr/bin/python3 + +import serial, time +# Configure the serial driver +ser = serial.Serial() +# Communicate via RS232 +ser.port = "/dev/ttymxc0" +ser.baudrate = 115200 +ser.bytesize = serial.EIGHTBITS +ser.parity = serial.PARITY_NONE +ser.stopbits = serial.STOPBITS_ONE + +# Try to open the port +try: + ser.open() +except Exception as e: + print ("Error while opening the serial port: " + str(e)) + exit() + +# If the port is open, write Hello World and wait +# for a reply which must be terminated by an LF. +if ser.isOpen(): + try: + # Clear the buffers + ser.flushInput() + ser.flushOutput() + while True: + # Write to the serial port + ser.write("Hello World!\n".encode()) + # Write it immediately + ser.flush() + print("Write data!") + try: + # Now wait for the other side to send something + myvar = ser.read_until() # Wait for LF + except: + # If there was an error during receiving, print an error + myvar = b'Error receiving!' + + # Display the received data, which must be ASCII characters in this example + print("Read data! " + myvar.decode('ascii')) + time.sleep(0.05) + ser.close() + except Exception as e1: + print ("Error while communicating...:" + str(e1)) +else: + print ("Cannot open serial port!") diff --git a/docs/src/getting-started-mx8mm.md b/docs/src/getting-started-mx8mm.md index 21a07b7c6eab28f2152c2f8331cce686cc75f70c..86c170beb68c286ed3ab3b2920101a1f37069769 100644 --- a/docs/src/getting-started-mx8mm.md +++ b/docs/src/getting-started-mx8mm.md @@ -286,4 +286,110 @@ bitbake image-ktn The building of the new system image should go fairly fast, as most packages were build in previous steps. You should mainly see Python 3 packages and their dependencies being build. After the build process completes, retrieve the system image file, unpack it and write it to an SD card. -Once the SD card is done and inserted into the BL i.MX8MM, you can go to the [top](#getting-started-with-imx8mm) of this guide and follow the steps there to see this new system image booting. \ No newline at end of file +Once the SD card is done and inserted into the BL i.MX8MM, you can go to the [top](#getting-started-with-imx8mm) of this guide and follow the steps there to see this new system image booting. + +## Examples using Python 3 + +Now that the system image includes Python 3 and some additional modules to work with the BL i.MX8MMs hardware, why not try it out. + +### Serial Communication + +In this example you will use the `pySerial` module to communicate with a computer. First wire up the RS232 port of the BL i.MX8MM to a computer directly if it has an RS232 port or via a USB-to-Serial adapter. You can find the connector pin-outs of the BL i.MX8MM in the [board overview](board-mx8mm.md). Remember to switch the Rx and Tx lines when connecting the wires. Once done, turn on the BL i.MX8MM and log in. + +Try to run Python 3 and print something to the console: + +```shell +root@kontron-mx8mm:~# python3 +Python 3.8.2 (default, Feb 25 2020, 10:39:28) +[GCC 9.3.0] on linux +Type "help", "copyright", "credits" or "license" for more information. +>>> print("Hello World!") +Hello World! +>>> quit() +root@kontron-mx8mm:~# +``` + +Now it's time to create a small Python 3 serial test program. Open the *nano* editor: + +```shell +root@kontron-mx8mm:~# nano serial_test.py +``` + +and enter the following program code or download a copy of the file <a href="./files/serial_test.py" target="_blank">serial_test.py</a> + +```shell +#!/usr/bin/python3 + +import serial, time +# Configure the serial driver +ser = serial.Serial() +# Communicate via RS232 +ser.port = "/dev/ttymxc0" +ser.baudrate = 115200 +ser.bytesize = serial.EIGHTBITS +ser.parity = serial.PARITY_NONE +ser.stopbits = serial.STOPBITS_ONE + +# Try to open the port +try: + ser.open() +except Exception as e: + print ("Error while opening the serial port: " + str(e)) + exit() + +# If the port is open, write Hello World and wait +# for a reply which must be terminated by an LF. +if ser.isOpen(): + try: + # Clear the buffers + ser.flushInput() + ser.flushOutput() + while True: + # Write to the serial port + ser.write("Hello World!\n".encode()) + # Write it immediately + ser.flush() + print("Write data!") + try: + # Now wait for the other side to send something + myvar = ser.read_until() # Wait for LF + except: + # If there was an error during receiving, print an error + myvar = b'Error receiving!' + + # Display the received data, which must be ASCII characters in this example + print("Read data! " + myvar.decode('ascii')) + time.sleep(0.05) + ser.close() + except Exception as e1: + print ("Error while communicating...:" + str(e1)) +else: + print ("Cannot open serial port!") +``` + +Save the changes with *CTRL+O* and *Enter* and then leave the editor with *CTRL+X*. + +On the computer start a terminal program and open the serial port using these parameters: + +- Baud rate: 115200 +- Data bits: 8 +- Stop bits: 1 +- Parity bit: None + +Run the Python 3 program on the BL i.MX8MM with this command: + +```shell +python3 serial_test.py +``` + +The terminal windows on the computer should now display the text: + +> Hello World! + +While on the BL i.MX8MM the Python 3 program printed the text "*Write data!*" to the console and now waits for the computer to send something. If you now enter a text like "*Hello World 2!*" in the terminal program on the computer and send it to the BL i.MX8MM, the Python 3 program will print the following to the console: + +> Read data! Hello World 2! + +**Note:** When sending data from the computer to the BL i.MX8MM the last byte or character has to be a linefeed character, also referred to as LF, \n, ASCII decimal value 10 or hex value A. Some terminal or serial programs on the computer do this automatically, but there are exceptions which do not. If there is no linefeed character in the data sent to the BL i.MX8MM, the Python 3 program will wait indefinitely until the linefeed character arrives, therefore during this wait the program might appear frozen. There are other function in pySerial to receive data which do not wait (block the program), the function `read_until` was chosen in this example for practical reasons. + +If you want to quit or terminate the program, press and hold the key combination *CTRL+C* until the program has ended. Feel free to modify the program or make your own and experiment with the serial port of the BL i.MX8MM sending and receiving data.