Task Owner:

Who owns this task and will approve the final deliverables? Lazar

Objectives & Goals:

1. How does this task relate to the value track(s)?

- All of the effort we put into improving our product lines should provide value to our customers.
- We need to be able to clearly articulate the value each improvement will provide in the following three value tracks:
    1. Development - The hardware chapter is important for evaluating the Omega modules for a new project and supporting developers in the development process.
    2. Deployment
    3. Production

2. Create a short statement explaining the objectives and goals for this ticket.

Can reference https://docs.onion.io/omega2-docs/uart1.html
Intro
- The Omega2 has two hardware serial UARTs, the Omega2S has three hardware serial UARTs
Context
- A universal asynchronous receiver/transmitter (UART) is a device used for serial communication between two devices.
- The UART uses the TX line to transmit data, and RX to receive data. When communicating with other devices, the TX on device A will send data to the RX on device B and vice versa.
Hardware
- Omega2/2+: There are two 2-pin Serial UARTs available
- Omega2S/2S+: There are three (3) 2-pin Serial UARTs available
  - UART logic level is 3.3V.
  - The default bootloader and operating system use UART0 to provide serial command line access.
  - All UARTs are UART Lite controllers that do not feature hardware flow control.
  - Support standard baud rates up to 345,600 b/s
- Pinout diagrams of Omega2, Omega2S with UART pins highlighted
Software
- UART interactions on the Omega2 are done using the virtual device files made available by sysfs.
  - Sysfs is a pseudo-file system that holds information about the Omega’s hardware in files, and lets the user control the hardware by editing the files.
  - UART0 accessible through /dev/ttyS0
  - UART1 accessible through /dev/ttyS1
  - UART2 accessible through /dev/ttyS2 (Omega2S/2S+ only)
- Interacting with the I2C bus
  - Command line
    - Reference: https://docs.onion.io/omega2-docs/uart1.html#using-the-command-line-1
    - Interact with the UART virtual device file
      - Send data on UART1: echo "my message" > /dev/ttyS1
      - Read data received on UART1: cat /dev/ttyS1 and wait
        
        Good for basic testing
  - Screen Utility
    - This utility allows the user to use a terminal interface with a UART - any data that’s received will be shown immediately, user can type to send data
    - Installation instructions:
      - opkg update
      - opkg install screen
    - Usage instructions:
      - To use UART1 with screen: screen /dev/ttyS1
        
        Any keys or letters you type are immediately sent to the UART (ie. to the device connected to it)
        
        The terminal will immediately display any data received from the UART (ie. from the device connected to it)
      - To end a screen session, type Ctrl-a then k
      - More information on using screen: https://linux.die.net/man/1/screen
- Python
  - Recommended module: pyserial
  - Installation instructions:
    - Opkg update
    - Opkg install python3-pip
    - pip3 install pyserial
  - How to use the module: see module documentation at https://pythonhosted.org/pyserial/shortintro.html

Reference Material:

1. Provide hyperlinks for helpful and related information.

Deliverables or Desired Outcome:

1. What are the task owners expectations?

Articles should be succinct, and minimalist.
These are MVP articles, and we will expand on them as users provide feedback and requests.
All articles from the Hardware chapter will go in the hardware branch.

2. What does the task owner require for a successful completion of the ticket?

i.e. sample code, drawings, documents etc.
a succinct article that follows our current style guide based on the original article

Date Required By:

1. When is the scope required to be completed?

no date has been specified

2. Is this a hard date? Specify if the task is a dependency of another task or if it will impact a customer requirement.

Ticket #44 has a dependency on this ticket to be completed

remingtontr commented 5 months ago

Ready for initial review.

I did not include content that was not referenced in the outline.

amsiotdeveloper commented 5 months ago

@greenbreakfast this article is ready for your review. @remingtontr just has a couple minor touch ups that should only take a couple mins.

Please see my comments in slack documentation channel.

greenbreakfast commented 5 months ago

@remingtontr it looks good to me. Made a few comments - mostly about how Python 2.x is deprecated. After that's resolved it should be good for a PR. The new markdown file should go into the docs/hardware-interfaces directory

OnionIoT / documentation

Article 5.5.1 UART #55