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.

Intro

I2C (Inter-Integrated Circuit), sometimes called Two-Wire Interface, is a serial interface used to quickly and easily connect multiple devices to controllers and processors such as the Omega2.
The Omega2 has one hardware I2C bus

Context

Communication is performed over 2 data lanes, each given their own pin on the Omega2:
- Clock (SCL) - Signals when data is being transferred
- Data (SDA) - Carries the data to be transferred
The I2C bus uses a master-worker architecture
- Many workers on an I2C bus
- Bus masters are devices that are in control of when and to whom they send and receive data.
  - Masters send commands which include the address of the slave who should receive it.
  - When using I2C with the Omega2, the Omega2 is configured to be the only bus master.
- Bus workers are devices that respond to masters when they receive a command addressed to them.
  - Each worker is identified with a hexadecimal address (eg. 0x27).
  - Worker will safely ignore commands not addressed to them.
- Masters and workers operate in either of two modes:
  - transmit - sending data
  - receive - receiving data

Hardware

Hardware-based I2C controller
- Logic level is 3.3V
- Can operate in host-mode only
- Default: standard mode (100kbps)
  - Fast mode (400kbps) is also supported
    - Pinout diagrams of Omega2, Omega2S with I2C pins highlighted

Software

I2C bus interface is available at /dev/i2c-0
Interacting with the I2C bus
- Command line:
  - Use the i2c-tools command line program
  - Good for basic testing
  - Installation instructions:
    - opkg update
    - Opkg install i2c-tools
  - Usage instructions: link to https://linuxhint.com/i2c-linux-utilities/
- C/C++
  - Recommended library: libi2c
  - How to use the library: See source code at https://git.kernel.org/pub/scm/utils/i2c-tools/i2c-tools.git/tree/
  - Future notes: look at
    - https://github.com/amaork/libi2c
- Python
  - Recommended module: python3-smbus
  - Installation instructions:
    - Opkg update
    - Opkg install python3-smbus
  - How to use the module: See source code at https://git.kernel.org/pub/scm/utils/i2c-tools/i2c-tools.git/tree/py-smbus/smbusmodule.c

Reference Material:

1. Provide hyperlinks for helpful and related information.

More Resources (just links to other resources) Default I2C bus clock speed and how it can be changed: https://community.onion.io/topic/4332/faq-what-is-the-default-i2c-bus-clock-speed-can-i-change-it-to-400khz Setting up a software-based (bit-band) I2C bus: https://community.onion.io/topic/4333/faq-how-can-i-make-a-software-based-bit-bang-i2c-bus-can-i-use-any-2-gpios-as-an-i2c-bus

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

greenbreakfast commented 3 months ago

Hi @amsiotdeveloper , this article was completed last month as an example of a minimally viable article that can be used as a template for the rest of the articles in the hardware chapter. See commit https://github.com/OnionIoT/documentation/commit/bd5d98234457999df724df3955ffb1b78466c7fb and the updated article at https://documentation.onioniot.com/hardware-interfaces/i2c

We can go ahead and close this ticket

remingtontr commented 3 months ago

Ready for initial review.

amsiotdeveloper commented 3 months ago

@remingtontr good work! Just a couple small syntax revisions and a reminder about style guid for the "Tip" I don't think we have a way to show that style in google docs so I just added the comment as a reminder.

@greenbreakfast this article is ready for your final review.

greenbreakfast commented 2 months ago

@remingtontr reviewed, left a comment and a few suggestions. Looks great otherwise