aboutsummaryrefslogtreecommitdiff
path: root/docs/i2c_driver.md
diff options
context:
space:
mode:
authorJames Young <18669334+noroadsleft@users.noreply.github.com>2020-03-15 20:29:11 -0700
committerGitHub <noreply@github.com>2020-03-15 20:29:11 -0700
commitb272c035ba7fa8555a88c922b3e94c3f3817c4ff (patch)
treea5c9a1f6e4a1d9c02b72a12e33b2f9e69b5bf85b /docs/i2c_driver.md
parent5f1f370463d818a5283a17001ad832073efc45a4 (diff)
downloadqmk_firmware-b272c035ba7fa8555a88c922b3e94c3f3817c4ff.tar.gz
qmk_firmware-b272c035ba7fa8555a88c922b3e94c3f3817c4ff.zip
[Docs] Random Fixes (#8340)
* fix CLI section links in the Summary * fix heading in Pointing Device doc * fix headings in PS/2 Mouse Support doc * add explicit section ids to I2C Master Driver doc * reformat GPIO Controls table Much like the I2C Master Driver doc, I found this a bit less than ideal to read. (The table was actually wider than the space available for it.) Reformatted so each GPIO function is an H3 heading, followed by a paragraph and a table of each architecture's old-style function. * migrate changes from I2C Master Driver doc to Japanese translation * add explicit anchors to I2C Master Driver docs * fix code block language markers The language markers are case-sensitive; using the wrong case means the syntax highlighting doesn't work. Good: ```c Bad: ```C * restore Japanese I2C Master Driver doc to current master Can't update the internal tracking references accurately until the changes to the English doc are committed to master. * add explicit anchors to edited files * change ChibiOS/ARM to ARM/ChibiOS Because ARM/ATSAM is also a thing that exists. * fix code block language markers again Used the wrong markers in a few spots. Also these are apparently always supposed to be lowercase. * add section anchors to cli.md * restore table formatting on GPIO Control doc * remove changes to _summary.md
Diffstat (limited to 'docs/i2c_driver.md')
-rw-r--r--docs/i2c_driver.md24
1 files changed, 12 insertions, 12 deletions
diff --git a/docs/i2c_driver.md b/docs/i2c_driver.md
index c9f53ef0d..d28a20fa1 100644
--- a/docs/i2c_driver.md
+++ b/docs/i2c_driver.md
@@ -1,8 +1,8 @@
1# I2C Master Driver 1# I2C Master Driver :id=i2c-master-driver
2 2
3The I2C Master drivers used in QMK have a set of common functions to allow portability between MCUs. 3The I2C Master drivers used in QMK have a set of common functions to allow portability between MCUs.
4 4
5## An important note on I2C Addresses 5## An important note on I2C Addresses :id=note-on-i2c-addresses
6 6
7All of the addresses expected by this driver should be pushed to the upper 7 bits of the address byte. Setting 7All of the addresses expected by this driver should be pushed to the upper 7 bits of the address byte. Setting
8the lower bit (indicating read/write) will be done by the respective functions. Almost all I2C addresses listed 8the lower bit (indicating read/write) will be done by the respective functions. Almost all I2C addresses listed
@@ -15,7 +15,7 @@ You can either do this on each call to the functions below, or once in your defi
15 15
16See https://www.robot-electronics.co.uk/i2c-tutorial for more information about I2C addressing and other technical details. 16See https://www.robot-electronics.co.uk/i2c-tutorial for more information about I2C addressing and other technical details.
17 17
18## Available functions 18## Available functions :id=available-functions
19 19
20|Function |Description | 20|Function |Description |
21|------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 21|------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -27,7 +27,7 @@ See https://www.robot-electronics.co.uk/i2c-tutorial for more information about
27|`i2c_status_t i2c_readReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);` |Same as the `i2c_receive` function but `regaddr` sets from where in the slave the data will be read. | 27|`i2c_status_t i2c_readReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);` |Same as the `i2c_receive` function but `regaddr` sets from where in the slave the data will be read. |
28|`i2c_status_t i2c_stop(void);` |Ends an I2C transaction. | 28|`i2c_status_t i2c_stop(void);` |Ends an I2C transaction. |
29 29
30### Function Return 30### Function Return :id=function-return
31 31
32All the above functions, except `void i2c_init(void);` return the following truth table: 32All the above functions, except `void i2c_init(void);` return the following truth table:
33 33
@@ -38,9 +38,9 @@ All the above functions, except `void i2c_init(void);` return the following trut
38|`I2C_STATUS_TIMEOUT`|-2 |Operation timed out. | 38|`I2C_STATUS_TIMEOUT`|-2 |Operation timed out. |
39 39
40 40
41## AVR 41## AVR :id=avr
42 42
43### Configuration 43### Configuration :id=avr-configuration
44 44
45The following defines can be used to configure the I2C master driver. 45The following defines can be used to configure the I2C master driver.
46 46
@@ -50,12 +50,12 @@ The following defines can be used to configure the I2C master driver.
50 50
51AVRs usually have set GPIO which turn into I2C pins, therefore no further configuration is required. 51AVRs usually have set GPIO which turn into I2C pins, therefore no further configuration is required.
52 52
53## ARM 53## ARM :id=arm
54 54
55For ARM the Chibios I2C HAL driver is under the hood. 55For ARM the Chibios I2C HAL driver is under the hood.
56This section assumes an STM32 MCU. 56This section assumes an STM32 MCU.
57 57
58### Configuration 58### Configuration :id=arm-configuration
59 59
60The configuration for ARM MCUs can be quite complex as often there are multiple I2C drivers which can be assigned to a variety of ports. 60The configuration for ARM MCUs can be quite complex as often there are multiple I2C drivers which can be assigned to a variety of ports.
61 61
@@ -90,7 +90,7 @@ The ChibiOS I2C driver configuration depends on STM32 MCU:
90 STM32F1xx, STM32F2xx, STM32F4xx, STM32L0xx and STM32L1xx use I2Cv1; 90 STM32F1xx, STM32F2xx, STM32F4xx, STM32L0xx and STM32L1xx use I2Cv1;
91 STM32F0xx, STM32F3xx, STM32F7xx and STM32L4xx use I2Cv2; 91 STM32F0xx, STM32F3xx, STM32F7xx and STM32L4xx use I2Cv2;
92 92
93#### I2Cv1 93#### I2Cv1 :id=i2cv1
94STM32 MCUs allow for different clock and duty parameters when configuring I2Cv1. These can be modified using the following parameters, using <https://www.playembedded.org/blog/stm32-i2c-chibios/#I2Cv1_configuration_structure> as a reference: 94STM32 MCUs allow for different clock and duty parameters when configuring I2Cv1. These can be modified using the following parameters, using <https://www.playembedded.org/blog/stm32-i2c-chibios/#I2Cv1_configuration_structure> as a reference:
95 95
96| Variable | Default | 96| Variable | Default |
@@ -99,7 +99,7 @@ STM32 MCUs allow for different clock and duty parameters when configuring I2Cv1.
99| `I2C1_CLOCK_SPEED` | `100000` | 99| `I2C1_CLOCK_SPEED` | `100000` |
100| `I2C1_DUTY_CYCLE` | `STD_DUTY_CYCLE` | 100| `I2C1_DUTY_CYCLE` | `STD_DUTY_CYCLE` |
101 101
102#### I2Cv2 102#### I2Cv2 :id=i2cv2
103STM32 MCUs allow for different timing parameters when configuring I2Cv2. These can be modified using the following parameters, using <https://www.st.com/en/embedded-software/stsw-stm32126.html> as a reference: 103STM32 MCUs allow for different timing parameters when configuring I2Cv2. These can be modified using the following parameters, using <https://www.st.com/en/embedded-software/stsw-stm32126.html> as a reference:
104 104
105| Variable | Default | 105| Variable | Default |
@@ -117,10 +117,10 @@ STM32 MCUs allow for different "alternate function" modes when configuring GPIO
117| `I2C1_SCL_PAL_MODE` | `4` | 117| `I2C1_SCL_PAL_MODE` | `4` |
118| `I2C1_SDA_PAL_MODE` | `4` | 118| `I2C1_SDA_PAL_MODE` | `4` |
119 119
120#### Other 120#### Other :id=other
121You can also overload the `void i2c_init(void)` function, which has a weak attribute. If you do this the configuration variables above will not be used. Please consult the datasheet of your MCU for the available GPIO configurations. The following is an example initialization function: 121You can also overload the `void i2c_init(void)` function, which has a weak attribute. If you do this the configuration variables above will not be used. Please consult the datasheet of your MCU for the available GPIO configurations. The following is an example initialization function:
122 122
123```C 123```c
124void i2c_init(void) 124void i2c_init(void)
125{ 125{
126 setPinInput(B6); // Try releasing special pins for a short time 126 setPinInput(B6); // Try releasing special pins for a short time