Skip to content

Commit e429fc0

Browse files
tenbahttenbaht
committed
fix tenbaht#28: I2C library complete, updated documentation
1 parent 0d91a1a commit e429fc0

2 files changed

Lines changed: 91 additions & 20 deletions

File tree

‎docs/api/I2C.md‎

Lines changed: 65 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -8,27 +8,47 @@ deadlock situations, it allows for communication using a repeated start
88
condition as required by some devices, the code is much more compact and the
99
structure is easier to understand.
1010

11-
The current state of the port is quite incomplete. Missing parts:
1211

13-
- read functions
14-
- speed setting (100kHz only)
15-
- pullup setting
16-
- does not include the deadlock protection
12+
## API
1713

14+
This is a pre-instantiated singleton library. It is not possible to use more
15+
than one instance per sketch or to change the instance name.
1816

19-
## Error codes
17+
The API syntax is very similar to the original C++ syntax. Some name
18+
mangeling was needed to distinguish the different variant of the `read()`
19+
and `write()` method. Apart from this replacing the dots in the method names
20+
for underscores is all it needs.
2021

21-
Return values for functions that use the timeOut feature will return at what
22-
point in the transmission the timeout occurred.
22+
The pullup setting is missing because this function is supported by the STM8
23+
hardware.
2324

24-
All possible return values:
2525

26-
Errorcode | Meaning
27-
---: |---
28-
0 |Function executed with no errors
29-
1-7 |Timeout occurred, see above list
30-
8-0xFF|See datasheet for exact meaning
26+
Arduino syntax |sduino syntax
27+
-------------------- |---------------------
28+
`I2C.begin()` |`I2C_begin()`
29+
`I2C.end()` |`I2C_end()`
30+
`I2C.timeOut(val)` |`I2C_timeOut(val)`
31+
`I2C.setSpeed(mode)` |`I2C_setSpeed(mode)`
32+
`I2C.pullup(active)` |not implemented
33+
`I2C.scan()` |`I2C_scan()`
34+
`n = I2C.available()` |`n = I2C_available()`
35+
`val = I2C.receive()` |`val = I2C_receive()`
36+
`I2C.write(addr, val)` |`I2C_write(addr, val)`
37+
`I2C.write(addr, reg, val)` |`I2C_write_reg(addr, reg, val)`
38+
`I2C.write(addr, reg, string)` |`I2C_write_s(addr, reg, string)`
39+
`I2C.write(addr, reg, *data, len)` |`I2C_write_sn(addr, reg, *data, len)`
40+
`I2C.read(addr, n)` |`I2C_read(addr, n)`
41+
`I2C.read(addr, reg, n)` |`I2C_read_reg(addr, reg, n)`
42+
`I2C.read(addr, n, *buf)` |`I2C_readbuf(addr, n, *buf)`
43+
`I2C.read(addr, reg, n, *buf)` |`I2C_readbuf_reg(addr, reg, n, *buf)`
44+
45+
46+
47+
### Error codes
3148

49+
All functions return an error code. Return values for functions that use the
50+
timeOut feature will return at what point in the transmission the timeout
51+
occurred.
3252

3353
Looking at a full communication sequence between a master and slave
3454
(transmit data and then readback data) there a total of 7 points in the
@@ -37,6 +57,7 @@ the returned value.
3757

3858
Errorcode | Meaning: Waiting for...
3959
---: |---
60+
0 |Function executed with no errors
4061
1 |Waiting for successful completion of a Start bit
4162
2 |Waiting for ACK/NACK while addressing slave in transmit mode (MT)
4263
3 |Waiting for ACK/NACK while sending data to the slave
@@ -46,7 +67,15 @@ Errorcode | Meaning: Waiting for...
4667
7 |Waiting for successful completion of the Stop bit
4768

4869

49-
## AVR error codes
70+
71+
### AVR error codes
72+
73+
For reference: The codes listed below where defined for the AVR, but they
74+
don't exist for the STM8 implementation. Combining the values of SR1 and SR2
75+
it would be possible to implement most of these conditions (apart from
76+
0x20), but so far I haven't seen any program needing these values, so I
77+
didn't implement this.
78+
5079

5180
Status Codes| for Master Transmitter Mode
5281
--- |---
@@ -74,5 +103,24 @@ Status Codes| independed of mode
74103
0xF8 |No relevant state information available; TWINT = “0”
75104
0x00 |Bus error due to an illegal START or STOP condition
76105

77-
Es braucht also SR1 und SR2
78-
0x20 ist nicht abzubilden.
106+
107+
108+
109+
## inner workings
110+
111+
start(): Sends start bit, does not wait for SB flag.
112+
sendAddress()
113+
114+
115+
## Further reading
116+
117+
Programming the I2C communication on the register level is quite complex for
118+
the STM8, especially in receive mode. The most detailed information on this
119+
topic is the
120+
121+
- application note AN3281 bundeled with
122+
- the related source code package [STSW-STM8004](https://www.st.com/en/embedded-software/stsw-stm8004.html)
123+
124+
Downloading from the ST website requires a (free) registration. Somebody
125+
uploaded the full package to github:
126+
https://github.com/jiaohaitao/stsw-stm8004

‎docs/api/LiquidCrystal_I2C.md‎

Lines changed: 26 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -29,13 +29,13 @@ underscores is all it needs.
2929

3030
The original version of the LiquidCystal_I2C library requires the
3131
definition of the LCD size and the desired character size (8 or 10 pixel
32-
height) at the instantiation uses a parameterless begin() method.
32+
height) at the instantiation and uses a parameterless `begin()` method.
3333

3434
This differs slightly from the semantic of the regular Arduino
3535
LiquidCrystal library using the parallel interface. There, the
3636
instantiation defines only the electrical connection (the used pin
3737
numbers) and defines the logical properties (cols, rows, charsize) later
38-
with the begin method.
38+
with the `begin()` method.
3939

4040
As an addition to the Arduino version of this library this port
4141
supports both initialization styles.
@@ -45,7 +45,7 @@ Arduino syntax |sduino syntax
4545
-------------------- |---------------------
4646
`LiquidCrystal_I2C lcd(i2c_addr,cols,rows,charsize)` |`LiquidCrystal_I2C (lcd,i2c_addr,rows,cols,charsize)`
4747
`LiquidCrystal_I2C lcd(i2c_addr,cols,rows)` |`LiquidCrystal_I2C (lcd,i2c_addr,rows)`
48-
not allowed |`LiquidCrystal_I2C (lcd,i2c_addr)`
48+
not allowed |`LiquidCrystal_I2C (lcd,i2c_addr)`
4949
`lcd.init(i2c_addr,cols,rows,charsize)` |`lcd_init(i2c_addr,cols,rows,charsize)`
5050
`lcd.begin()` |`lcd_begin()`
5151
not allowed |`lcd_begin_wh(cols,rows)`
@@ -168,6 +168,29 @@ void loop() {
168168
```
169169
170170
171+
## Pin connections
172+
173+
The table shows the most common connection scheme as used by the popular
174+
backpack boards from China:
175+
176+
PCF8574 bit |Backpack pin |LCD signal |LCD pin
177+
--- |--- |--- |---
178+
0 |13 |RS |4
179+
1 |12 |R/-W |5
180+
2 |11 |EN |6
181+
3 |1 |LED- (open collector, inverted)|16
182+
4 |6 |D4 |11
183+
5 |5 |D5 |12
184+
6 |4 |D6 |13
185+
7 |3 |D7 |14
186+
187+
The numbering of the LCD connector counts in the opposite directions on the
188+
the LCD and the backpack module. It looks like the person designing the PCB
189+
layout got confused by the backwards mounting position ;-) But in reality it
190+
doesn't matter, they both fit together nicely. It is just a unfortunate
191+
silkscreen printing.
192+
193+
171194
172195
173196
## Possible improvements

0 commit comments

Comments
 (0)