vin/qmk_firmware
1
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Fix anchor IDs for some API references (#21345)

Browse Source
This commit is contained in:
Ryan 2023-06-24 17:44:50 +10:00 committed by GitHub
parent 1e05bad1ba
commit 12edfc0c69
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 133 additions and 133 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

84
docs/feature_hd44780.md
View File

@ -1,6 +1,6 @@
# HD44780 LCD Driver # HD44780 LCD Driver :id=hd44780-lcd-driver
## Supported Hardware ## Supported Hardware :id=supported-hardware
LCD modules using [HD44780U](https://www.sparkfun.com/datasheets/LCD/HD44780.pdf) IC or equivalent, communicating in 4-bit mode. LCD modules using [HD44780U](https://www.sparkfun.com/datasheets/LCD/HD44780.pdf) IC or equivalent, communicating in 4-bit mode.
@ -11,7 +11,7 @@ LCD modules using [HD44780U](https://www.sparkfun.com/datasheets/LCD/HD44780.pdf
To run these modules at 3.3V, an additional MAX660 voltage converter IC must be soldered on, along with two 10µF capacitors. See [this page](https://www.codrey.com/electronic-circuits/hack-your-16x2-lcd/) for more details. To run these modules at 3.3V, an additional MAX660 voltage converter IC must be soldered on, along with two 10µF capacitors. See [this page](https://www.codrey.com/electronic-circuits/hack-your-16x2-lcd/) for more details.
## Usage ## Usage :id=usage
Add the following to your `rules.mk`: Add the following to your `rules.mk`:
@ -19,7 +19,7 @@ Add the following to your `rules.mk`:
HD44780_ENABLE = yes HD44780_ENABLE = yes
``` ```
## Basic Configuration ## Basic Configuration :id=basic-configuration
Add the following to your `config.h`: Add the following to your `config.h`:
@ -33,9 +33,9 @@ Add the following to your `config.h`:
|`HD44780_DISPLAY_LINES`|`2` |The number of visible lines on the display | |`HD44780_DISPLAY_LINES`|`2` |The number of visible lines on the display |
|`HD44780_WRAP_LINES` |*Not defined* |If defined, input characters will wrap to the next line | |`HD44780_WRAP_LINES` |*Not defined* |If defined, input characters will wrap to the next line |
## Examples ## Examples :id=examples
### Hello World ### Hello World :id=example-hello-world
Add the following to your `keymap.c`: Add the following to your `keymap.c`:
@ -46,7 +46,7 @@ void keyboard_post_init_user(void) {
} }
``` ```
### Custom Character Definition ### Custom Character Definition :id=example-custom-character
Up to eight custom characters can be defined. This data is stored in the Character Generator RAM (CGRAM), and is not persistent across power cycles. Up to eight custom characters can be defined. This data is stored in the Character Generator RAM (CGRAM), and is not persistent across power cycles.
@ -77,15 +77,15 @@ void keyboard_post_init_user(void) {
} }
``` ```
## API ## API :id=api
### `void hd44780_init(bool cursor, bool blink)` ### `void hd44780_init(bool cursor, bool blink)` :id=api-hd44780-init
Initialize the display. Initialize the display.
This function should be called only once, before any of the other functions can be called. This function should be called only once, before any of the other functions can be called.
#### Arguments #### Arguments :id=api-hd44780-init-arguments
- `bool cursor` - `bool cursor`
Whether to show the cursor. Whether to show the cursor.
@ -94,7 +94,7 @@ This function should be called only once, before any of the other functions can
--- ---
### `void hd44780_clear(void)` ### `void hd44780_clear(void)` :id=api-hd44780-clear
Clear the display. Clear the display.
@ -102,7 +102,7 @@ This function is called on init.
--- ---
### `void hd44780_home(void)` ### `void hd44780_home(void)` :id=api-hd44780-home
Move the cursor to the home position. Move the cursor to the home position.
@ -110,13 +110,13 @@ This function is called on init.
--- ---
### `void hd44780_on(bool cursor, bool blink)` ### `void hd44780_on(bool cursor, bool blink)` :id=api-hd44780-on
Turn the display on, and/or set the cursor properties. Turn the display on, and/or set the cursor properties.
This function is called on init. This function is called on init.
#### Arguments #### Arguments :id=api-hd44780-on-arguments
- `bool cursor` - `bool cursor`
Whether to show the cursor. Whether to show the cursor.
@ -125,17 +125,17 @@ This function is called on init.
--- ---
### `void hd44780_off(void)` ### `void hd44780_off(void)` :id=api-hd44780-off
Turn the display off. Turn the display off.
--- ---
### `void hd44780_set_cursor(uint8_t col, uint8_t line)` ### `void hd44780_set_cursor(uint8_t col, uint8_t line)` :id=api-hd44780-set-cursor
Move the cursor to the specified position on the display. Move the cursor to the specified position on the display.
#### Arguments #### Arguments :id=api-hd44780-set-cursor-arguments
- `uint8_t col` - `uint8_t col`
The column number to move to, from 0 to 15 on 16x2 displays. The column number to move to, from 0 to 15 on 16x2 displays.
@ -144,48 +144,48 @@ Move the cursor to the specified position on the display.
--- ---
### `void hd44780_putc(char c)` ### `void hd44780_putc(char c)` :id=api-hd44780-putc
Print a character to the display. The newline character `\n` will move the cursor to the start of the next line. Print a character to the display. The newline character `\n` will move the cursor to the start of the next line.
The exact character shown may depend on the ROM code of your particular display - refer to the datasheet for the full character set. The exact character shown may depend on the ROM code of your particular display - refer to the datasheet for the full character set.
#### Arguments #### Arguments :id=api-hd44780-putc-arguments
- `char c` - `char c`
The character to print. The character to print.
--- ---
### `void hd44780_puts(const char *s)` ### `void hd44780_puts(const char *s)` :id=api-hd44780-puts
Print a string of characters to the display. Print a string of characters to the display.
#### Arguments #### Arguments :id=api-hd44780-puts-arguments
- `const char *s` - `const char *s`
The string to print. The string to print.
--- ---
### `void hd44780_puts_P(const char *s)` ### `void hd44780_puts_P(const char *s)` :id=api-hd44780-puts-p
Print a string of characters from PROGMEM to the display. Print a string of characters from PROGMEM to the display.
On ARM devices, this function is simply an alias of `hd44780_puts()`. On ARM devices, this function is simply an alias of `hd44780_puts()`.
#### Arguments #### Arguments :id=api-hd44780-puts-p-arguments
- `const char *s` - `const char *s`
The PROGMEM string to print (ie. `PSTR("Hello")`). The PROGMEM string to print (ie. `PSTR("Hello")`).
--- ---
### `void hd44780_define_char(uint8_t index, uint8_t *data)` ### `void hd44780_define_char(uint8_t index, uint8_t *data)` :id=api-hd44780-define-char
Define a custom character. Define a custom character.
#### Arguments #### Arguments :id=api-hd44780-define-char-arguments
- `uint8_t index` - `uint8_t index`
The index of the custom character to define, from 0 to 7. The index of the custom character to define, from 0 to 7.
@ -194,13 +194,13 @@ Define a custom character.
--- ---
### `void hd44780_define_char_P(uint8_t index, const uint8_t *data)` ### `void hd44780_define_char_P(uint8_t index, const uint8_t *data)` :id=api-hd44780-define-char-p
Define a custom character from PROGMEM. Define a custom character from PROGMEM.
On ARM devices, this function is simply an alias of `hd44780_define_char()`. On ARM devices, this function is simply an alias of `hd44780_define_char()`.
#### Arguments #### Arguments :id=api-hd44780-define-char-p-arguments
- `uint8_t index` - `uint8_t index`
The index of the custom character to define, from 0 to 7. The index of the custom character to define, from 0 to 7.
@ -209,21 +209,21 @@ On ARM devices, this function is simply an alias of `hd44780_define_char()`.
--- ---
### `bool hd44780_busy(void)` ### `bool hd44780_busy(void)` :id=api-hd44780-busy
Indicates whether the display is currently processing, and cannot accept instructions. Indicates whether the display is currently processing, and cannot accept instructions.
#### Return Value #### Return Value :id=api-hd44780-busy-arguments
`true` if the display is busy. `true` if the display is busy.
--- ---
### `void hd44780_write(uint8_t data, bool isData)` ### `void hd44780_write(uint8_t data, bool isData)` :id=api-hd44780-write
Write a byte to the display. Write a byte to the display.
#### Arguments #### Arguments :id=api-hd44780-write-arguments
- `uint8_t data` - `uint8_t data`
The byte to send to the display. The byte to send to the display.
@ -232,67 +232,67 @@ Write a byte to the display.
--- ---
### `uint8_t hd44780_read(bool isData)` ### `uint8_t hd44780_read(bool isData)` :id=api-hd44780-read
Read a byte from the display. Read a byte from the display.
#### Arguments #### Arguments :id=api-hd44780-read-arguments
- `bool isData` - `bool isData`
Whether to read the current cursor position, or the character at the cursor. Whether to read the current cursor position, or the character at the cursor.
#### Return Value #### Return Value :id=api-hd44780-read-return
If `isData` is `true`, the returned byte will be the character at the current DDRAM address. Otherwise, it will be the current DDRAM address and the busy flag. If `isData` is `true`, the returned byte will be the character at the current DDRAM address. Otherwise, it will be the current DDRAM address and the busy flag.
--- ---
### `void hd44780_command(uint8_t command)` ### `void hd44780_command(uint8_t command)` :id=api-hd44780-command
Send a command to the display. Refer to the datasheet and `hd44780.h` for the valid commands and defines. Send a command to the display. Refer to the datasheet and `hd44780.h` for the valid commands and defines.
This function waits for the display to clear the busy flag before sending the command. This function waits for the display to clear the busy flag before sending the command.
#### Arguments #### Arguments :id=api-hd44780-command-arguments
- `uint8_t command` - `uint8_t command`
The command to send. The command to send.
--- ---
### `void hd44780_data(uint8_t data)` ### `void hd44780_data(uint8_t data)` :id=api-hd44780-data
Send a byte of data to the display. Send a byte of data to the display.
This function waits for the display to clear the busy flag before sending the data. This function waits for the display to clear the busy flag before sending the data.
#### Arguments #### Arguments :id=api-hd44780-data-arguments
- `uint8_t data` - `uint8_t data`
The byte of data to send. The byte of data to send.
--- ---
### `void hd44780_set_cgram_address(uint8_t address)` ### `void hd44780_set_cgram_address(uint8_t address)` :id=api-hd44780-set-cgram-address
Set the CGRAM address. Set the CGRAM address.
This function is used when defining custom characters. This function is used when defining custom characters.
#### Arguments #### Arguments :id=api-hd44780-set-cgram-address-arguments
- `uint8_t address` - `uint8_t address`
The CGRAM address to move to, from `0x00` to `0x3F`. The CGRAM address to move to, from `0x00` to `0x3F`.
--- ---
### `void hd44780_set_ddram_address(uint8_t address)` ### `void hd44780_set_ddram_address(uint8_t address)` :id=api-hd44780-set-ddram-address
Set the DDRAM address. Set the DDRAM address.
This function is used when printing characters to the display, and setting the cursor. This function is used when printing characters to the display, and setting the cursor.
#### Arguments #### Arguments :id=api-hd44780-set-ddram-address-arguments
- `uint8_t address` - `uint8_t address`
The DDRAM address to move to, from `0x00` to `0x7F`. The DDRAM address to move to, from `0x00` to `0x7F`.

60
docs/feature_send_string.md
View File

@ -1,4 +1,4 @@
# Send String # Send String :id=send-string
The Send String API is part of QMK's macro system. It allows for sequences of keystrokes to be sent automatically. The Send String API is part of QMK's macro system. It allows for sequences of keystrokes to be sent automatically.
@ -6,7 +6,7 @@ The full ASCII character set is supported, along with all of the keycodes in the
?> Unicode characters are **not** supported with this API -- see the [Unicode](feature_unicode.md) feature instead. ?> Unicode characters are **not** supported with this API -- see the [Unicode](feature_unicode.md) feature instead.
## Usage ## Usage :id=usage
Send String is enabled by default, so there is usually no need for any special setup. However, if it is disabled, add the following to your `rules.mk`: Send String is enabled by default, so there is usually no need for any special setup. However, if it is disabled, add the following to your `rules.mk`:
@ -14,7 +14,7 @@ Send String is enabled by default, so there is usually no need for any special s
SEND_STRING_ENABLE = yes SEND_STRING_ENABLE = yes
``` ```
## Basic Configuration ## Basic Configuration :id=basic-configuration
Add the following to your `config.h`: Add the following to your `config.h`:
@ -23,7 +23,7 @@ Add the following to your `config.h`:
|`SENDSTRING_BELL`|*Not defined* |If the [Audio](feature_audio.md) feature is enabled, the `\a` character (ASCII `BEL`) will beep the speaker.| |`SENDSTRING_BELL`|*Not defined* |If the [Audio](feature_audio.md) feature is enabled, the `\a` character (ASCII `BEL`) will beep the speaker.|
|`BELL_SOUND` |`TERMINAL_SOUND`|The song to play when the `\a` character is encountered. By default, this is an eighth note of C5. | |`BELL_SOUND` |`TERMINAL_SOUND`|The song to play when the `\a` character is encountered. By default, this is an eighth note of C5. |
## Keycodes ## Keycodes :id=keycodes
The Send String functions accept C string literals, but specific keycodes can be injected with the below macros. All of the keycodes in the [Basic Keycode range](keycodes_basic.md) are supported (as these are the only ones that will actually be sent to the host), but with an `X_` prefix instead of `KC_`. The Send String functions accept C string literals, but specific keycodes can be injected with the below macros. All of the keycodes in the [Basic Keycode range](keycodes_basic.md) are supported (as these are the only ones that will actually be sent to the host), but with an `X_` prefix instead of `KC_`.
@ -44,13 +44,13 @@ The following characters are also mapped to their respective keycodes for conven
|`\t` |`\x1B`|`TAB`|`KC_TAB` | |`\t` |`\x1B`|`TAB`|`KC_TAB` |
| |`\x7F`|`DEL`|`KC_DELETE` | | |`\x7F`|`DEL`|`KC_DELETE` |
### Language Support ### Language Support :id=language-support
By default, Send String assumes your OS keyboard layout is set to US ANSI. If you are using a different keyboard layout, you can [override the lookup tables used to convert ASCII characters to keystrokes](reference_keymap_extras.md#sendstring-support). By default, Send String assumes your OS keyboard layout is set to US ANSI. If you are using a different keyboard layout, you can [override the lookup tables used to convert ASCII characters to keystrokes](reference_keymap_extras.md#sendstring-support).
## Examples ## Examples :id=examples
### Hello World ### Hello World :id=example-hello-world
A simple custom keycode which types out "Hello, world!" and the Enter key when pressed. A simple custom keycode which types out "Hello, world!" and the Enter key when pressed.
@ -70,7 +70,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
} }
``` ```
### Keycode Injection ### Keycode Injection :id=example-keycode-injection
This example types out opening and closing curly braces, then taps the left arrow key to move the cursor between the two. This example types out opening and closing curly braces, then taps the left arrow key to move the cursor between the two.
@ -84,26 +84,26 @@ This example types Ctrl+A, then Ctrl+C, without releasing Ctrl.
SEND_STRING(SS_LCTL("ac")); SEND_STRING(SS_LCTL("ac"));
``` ```
## API ## API :id=api
### `void send_string(const char *string)` ### `void send_string(const char *string)` :id=api-send-string
Type out a string of ASCII characters. Type out a string of ASCII characters.
This function simply calls `send_string_with_delay(string, 0)`. This function simply calls `send_string_with_delay(string, 0)`.
#### Arguments #### Arguments :id=api-send-string-arguments
- `const char *string` - `const char *string`
The string to type out. The string to type out.
--- ---
### `void send_string_with_delay(const char *string, uint8_t interval)` ### `void send_string_with_delay(const char *string, uint8_t interval)` :id=api-send-string-with-delay
Type out a string of ASCII characters, with a delay between each character. Type out a string of ASCII characters, with a delay between each character.
#### Arguments #### Arguments :id=api-send-string-with-delay-arguments
- `const char *string` - `const char *string`
The string to type out. The string to type out.
@ -112,26 +112,26 @@ Type out a string of ASCII characters, with a delay between each character.
--- ---
### `void send_string_P(const char *string)` ### `void send_string_P(const char *string)` :id=api-send-string-p
Type out a PROGMEM string of ASCII characters. Type out a PROGMEM string of ASCII characters.
On ARM devices, this function is simply an alias for `send_string_with_delay(string, 0)`. On ARM devices, this function is simply an alias for `send_string_with_delay(string, 0)`.
#### Arguments #### Arguments :id=api-send-string-p-arguments
- `const char *string` - `const char *string`
The string to type out. The string to type out.
--- ---
### `void send_string_with_delay_P(const char *string, uint8_t interval)` ### `void send_string_with_delay_P(const char *string, uint8_t interval)` :id=api-send-string-with-delay-p
Type out a PROGMEM string of ASCII characters, with a delay between each character. Type out a PROGMEM string of ASCII characters, with a delay between each character.
On ARM devices, this function is simply an alias for `send_string_with_delay(string, interval)`. On ARM devices, this function is simply an alias for `send_string_with_delay(string, interval)`.
#### Arguments #### Arguments :id=api-send-string-with-delay-p-arguments
- `const char *string` - `const char *string`
The string to type out. The string to type out.
@ -140,76 +140,76 @@ On ARM devices, this function is simply an alias for `send_string_with_delay(str
--- ---
### `void send_char(char ascii_code)` ### `void send_char(char ascii_code)` :id=api-send-char
Type out an ASCII character. Type out an ASCII character.
#### Arguments #### Arguments :id=api-send-char-arguments
- `char ascii_code` - `char ascii_code`
The character to type. The character to type.
--- ---
### `void send_dword(uint32_t number)` ### `void send_dword(uint32_t number)` :id=api-send-dword
Type out an eight digit (unsigned 32-bit) hexadecimal value. Type out an eight digit (unsigned 32-bit) hexadecimal value.
The format is `[0-9a-f]{8}`, eg. `00000000` through `ffffffff`. The format is `[0-9a-f]{8}`, eg. `00000000` through `ffffffff`.
#### Arguments #### Arguments :id=api-send-dword-arguments
- `uint32_t number` - `uint32_t number`
The value to type, from 0 to 4,294,967,295. The value to type, from 0 to 4,294,967,295.
--- ---
### `void send_word(uint16_t number)` ### `void send_word(uint16_t number)` :id=api-send-word
Type out a four digit (unsigned 16-bit) hexadecimal value. Type out a four digit (unsigned 16-bit) hexadecimal value.
The format is `[0-9a-f]{4}`, eg. `0000` through `ffff`. The format is `[0-9a-f]{4}`, eg. `0000` through `ffff`.
#### Arguments #### Arguments :id=api-send-word-arguments
- `uint16_t number` - `uint16_t number`
The value to type, from 0 to 65,535. The value to type, from 0 to 65,535.
--- ---
### `void send_byte(uint8_t number)` ### `void send_byte(uint8_t number)` :id=api-send-bytes
Type out a two digit (8-bit) hexadecimal value. Type out a two digit (8-bit) hexadecimal value.
The format is `[0-9a-f]{2}`, eg. `00` through `ff`. The format is `[0-9a-f]{2}`, eg. `00` through `ff`.
#### Arguments #### Arguments :id=api-send-byte-arguments
- `uint8_t number` - `uint8_t number`
The value to type, from 0 to 255. The value to type, from 0 to 255.
--- ---
### `void send_nibble(uint8_t number)` ### `void send_nibble(uint8_t number)` :id=api-send-nibble
Type out a single hexadecimal digit. Type out a single hexadecimal digit.
The format is `[0-9a-f]{1}`, eg. `0` through `f`. The format is `[0-9a-f]{1}`, eg. `0` through `f`.
#### Arguments #### Arguments :id=api-send-nibble-arguments
- `uint8_t number` - `uint8_t number`
The value to type, from 0 to 15. The value to type, from 0 to 15.
--- ---
### `void tap_random_base64(void)` ### `void tap_random_base64(void)` :id=api-tap-random-base64
Type a pseudorandom character from the set `A-Z`, `a-z`, `0-9`, `+` and `/`. Type a pseudorandom character from the set `A-Z`, `a-z`, `0-9`, `+` and `/`.
--- ---
### `SEND_STRING(string)` ### `SEND_STRING(string)` :id=api-send-string-macro
Shortcut macro for `send_string_with_delay_P(PSTR(string), 0)`. Shortcut macro for `send_string_with_delay_P(PSTR(string), 0)`.
@ -217,7 +217,7 @@ On ARM devices, this define evaluates to `send_string_with_delay(string, 0)`.
--- ---
### `SEND_STRING_DELAY(string, interval)` ### `SEND_STRING_DELAY(string, interval)` :id=api-send-string-delay-macro
Shortcut macro for `send_string_with_delay_P(PSTR(string), interval)`. Shortcut macro for `send_string_with_delay_P(PSTR(string), interval)`.

50
docs/i2c_driver.md
View File

@ -72,7 +72,7 @@ Configuration-wise, you'll need to set up the peripheral as per your MCU's datas
The following configuration values depend on the specific MCU in use. The following configuration values depend on the specific MCU in use.
### I2Cv1 :id=i2cv1 ### I2Cv1 :id=arm-configuration-i2cv1
* STM32F1xx * STM32F1xx
* STM32F2xx * STM32F2xx
@ -88,7 +88,7 @@ See [this page](https://www.playembedded.org/blog/stm32-i2c-chibios/#7_I2Cv1_con
|`I2C1_CLOCK_SPEED` |`100000` | |`I2C1_CLOCK_SPEED` |`100000` |
|`I2C1_DUTY_CYCLE` |`STD_DUTY_CYCLE`| |`I2C1_DUTY_CYCLE` |`STD_DUTY_CYCLE`|
### I2Cv2 :id=i2cv2 ### I2Cv2 :id=arm-configuration-i2cv2
* STM32F0xx * STM32F0xx
* STM32F3xx * STM32F3xx
@ -105,9 +105,9 @@ See [this page](https://www.playembedded.org/blog/stm32-i2c-chibios/#8_I2Cv2_I2C
|`I2C1_TIMINGR_SCLH` |`38U` | |`I2C1_TIMINGR_SCLH` |`38U` |
|`I2C1_TIMINGR_SCLL` |`129U` | |`I2C1_TIMINGR_SCLL` |`129U` |
## Functions :id=functions ## API :id=api
### `void i2c_init(void)` ### `void i2c_init(void)` :id=api-i2c-init
Initialize the I2C driver. This function must be called only once, before any of the below functions can be called. Initialize the I2C driver. This function must be called only once, before any of the below functions can be called.
@ -126,28 +126,28 @@ void i2c_init(void) {
--- ---
### `i2c_status_t i2c_start(uint8_t address, uint16_t timeout)` ### `i2c_status_t i2c_start(uint8_t address, uint16_t timeout)` :id=api-i2c-start
Start an I2C transaction. Start an I2C transaction.
#### Arguments #### Arguments :id=api-i2c-start-arguments
- `uint8_t address` - `uint8_t address`
The 7-bit I2C address of the device (ie. without the read/write bit - this will be set automatically). The 7-bit I2C address of the device (ie. without the read/write bit - this will be set automatically).
- `uint16_t timeout` - `uint16_t timeout`
The time in milliseconds to wait for a response from the target device. The time in milliseconds to wait for a response from the target device.
#### Return Value #### Return Value :id=api-i2c-start-return
`I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`. `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
--- ---
### `i2c_status_t i2c_transmit(uint8_t address, uint8_t *data, uint16_t length, uint16_t timeout)` ### `i2c_status_t i2c_transmit(uint8_t address, uint8_t *data, uint16_t length, uint16_t timeout)` :id=api-i2c-transmit
Send multiple bytes to the selected I2C device. Send multiple bytes to the selected I2C device.
#### Arguments #### Arguments :id=api-i2c-transmit-arguments
- `uint8_t address` - `uint8_t address`
The 7-bit I2C address of the device. The 7-bit I2C address of the device.
@ -158,17 +158,17 @@ Send multiple bytes to the selected I2C device.
- `uint16_t timeout` - `uint16_t timeout`
The time in milliseconds to wait for a response from the target device. The time in milliseconds to wait for a response from the target device.
#### Return Value #### Return Value :id=api-i2c-transmit-return
`I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`. `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
--- ---
### `i2c_status_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout)` ### `i2c_status_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout)` :id=api-i2c-receive
Receive multiple bytes from the selected I2C device. Receive multiple bytes from the selected I2C device.
#### Arguments #### Arguments :id=api-i2c-receive-arguments
- `uint8_t address` - `uint8_t address`
The 7-bit I2C address of the device. The 7-bit I2C address of the device.
@ -179,17 +179,17 @@ Receive multiple bytes from the selected I2C device.
- `uint16_t timeout` - `uint16_t timeout`
The time in milliseconds to wait for a response from the target device. The time in milliseconds to wait for a response from the target device.
#### Return Value #### Return Value :id=api-i2c-receive-return
`I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`. `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
--- ---
### `i2c_status_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout)` ### `i2c_status_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout)` :id=api-i2c-writereg
Writes to a register with an 8-bit address on the I2C device. Writes to a register with an 8-bit address on the I2C device.
#### Arguments #### Arguments :id=api-i2c-writereg-arguments
- `uint8_t devaddr` - `uint8_t devaddr`
The 7-bit I2C address of the device. The 7-bit I2C address of the device.
@ -202,17 +202,17 @@ Writes to a register with an 8-bit address on the I2C device.
- `uint16_t timeout` - `uint16_t timeout`
The time in milliseconds to wait for a response from the target device. The time in milliseconds to wait for a response from the target device.
#### Return Value #### Return Value :id=api-i2c-writereg-return
`I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`. `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
--- ---
### `i2c_status_t i2c_writeReg16(uint8_t devaddr, uint16_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout)` ### `i2c_status_t i2c_writeReg16(uint8_t devaddr, uint16_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout)` :id=api-i2c-writereg16
Writes to a register with a 16-bit address (big endian) on the I2C device. Writes to a register with a 16-bit address (big endian) on the I2C device.
#### Arguments #### Arguments :id=api-i2c-writereg16-arguments
- `uint8_t devaddr` - `uint8_t devaddr`
The 7-bit I2C address of the device. The 7-bit I2C address of the device.
@ -225,17 +225,17 @@ Writes to a register with a 16-bit address (big endian) on the I2C device.
- `uint16_t timeout` - `uint16_t timeout`
The time in milliseconds to wait for a response from the target device. The time in milliseconds to wait for a response from the target device.
#### Return Value #### Return Value :id=api-i2c-writereg16-return
`I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`. `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
--- ---
### `i2c_status_t i2c_readReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout)` ### `i2c_status_t i2c_readReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout)` :id=api-i2c-readreg
Reads from a register with an 8-bit address on the I2C device. Reads from a register with an 8-bit address on the I2C device.
#### Arguments #### Arguments :id=api-i2c-readreg-arguments
- `uint8_t devaddr` - `uint8_t devaddr`
The 7-bit I2C address of the device. The 7-bit I2C address of the device.
@ -246,7 +246,7 @@ Reads from a register with an 8-bit address on the I2C device.
- `uint16_t timeout` - `uint16_t timeout`
The time in milliseconds to wait for a response from the target device. The time in milliseconds to wait for a response from the target device.
#### Return Value #### Return Value :id=api-i2c-readreg-return
`I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`. `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
@ -256,7 +256,7 @@ Reads from a register with an 8-bit address on the I2C device.
Reads from a register with a 16-bit address (big endian) on the I2C device. Reads from a register with a 16-bit address (big endian) on the I2C device.
#### Arguments #### Arguments :id=api-i2c-readreg16-arguments
- `uint8_t devaddr` - `uint8_t devaddr`
The 7-bit I2C address of the device. The 7-bit I2C address of the device.
@ -267,12 +267,12 @@ Reads from a register with a 16-bit address (big endian) on the I2C device.
- `uint16_t timeout` - `uint16_t timeout`
The time in milliseconds to wait for a response from the target device. The time in milliseconds to wait for a response from the target device.
#### Return Value #### Return Value :id=api-i2c-readreg16-return
`I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`. `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
--- ---
### `i2c_status_t i2c_stop(void)` ### `i2c_status_t i2c_stop(void)` :id=api-i2c-stop
Stop the current I2C transaction. Stop the current I2C transaction.

40
docs/spi_driver.md
View File

@ -1,8 +1,8 @@
# SPI Master Driver # SPI Master Driver :id=spi-master-driver
The SPI Master drivers used in QMK have a set of common functions to allow portability between MCUs. The SPI Master drivers used in QMK have a set of common functions to allow portability between MCUs.
## AVR Configuration ## AVR Configuration :id=avr-configuration
No special setup is required - just connect the `SS`, `SCK`, `MOSI` and `MISO` pins of your SPI devices to the matching pins on the MCU: No special setup is required - just connect the `SS`, `SCK`, `MOSI` and `MISO` pins of your SPI devices to the matching pins on the MCU:
@ -16,7 +16,7 @@ No special setup is required - just connect the `SS`, `SCK`, `MOSI` and `MISO` p
You may use more than one slave select pin, not just the `SS` pin. This is useful when you have multiple devices connected and need to communicate with them individually. You may use more than one slave select pin, not just the `SS` pin. This is useful when you have multiple devices connected and need to communicate with them individually.
`SPI_SS_PIN` can be passed to `spi_start()` to refer to `SS`. `SPI_SS_PIN` can be passed to `spi_start()` to refer to `SS`.
## ChibiOS/ARM Configuration ## ChibiOS/ARM Configuration :id=arm-configuration
You'll need to determine which pins can be used for SPI -- as an example, STM32 parts generally have multiple SPI peripherals, labeled SPI1, SPI2, SPI3 etc. You'll need to determine which pins can be used for SPI -- as an example, STM32 parts generally have multiple SPI peripherals, labeled SPI1, SPI2, SPI3 etc.
@ -49,19 +49,19 @@ Configuration-wise, you'll need to set up the peripheral as per your MCU's datas
As per the AVR configuration, you may choose any other standard GPIO as a slave select pin, which should be supplied to `spi_start()`. As per the AVR configuration, you may choose any other standard GPIO as a slave select pin, which should be supplied to `spi_start()`.
## Functions ## API :id=api
### `void spi_init(void)` ### `void spi_init(void)` :id=api-spi-init
Initialize the SPI driver. This function must be called only once, before any of the below functions can be called. Initialize the SPI driver. This function must be called only once, before any of the below functions can be called.
--- ---
### `bool spi_start(pin_t slavePin, bool lsbFirst, uint8_t mode, uint16_t divisor)` ### `bool spi_start(pin_t slavePin, bool lsbFirst, uint8_t mode, uint16_t divisor)` :id=api-spi-start
Start an SPI transaction. Start an SPI transaction.
#### Arguments #### Arguments :id=api-spi-start-arguments
- `pin_t slavePin` - `pin_t slavePin`
The QMK pin to assert as the slave select pin, eg. `B4`. The QMK pin to assert as the slave select pin, eg. `B4`.
@ -80,71 +80,71 @@ Start an SPI transaction.
- `uint16_t divisor` - `uint16_t divisor`
The SPI clock divisor, will be rounded up to the nearest power of two. This number can be calculated by dividing the MCU's clock speed by the desired SPI clock speed. For example, an MCU running at 8 MHz wanting to talk to an SPI device at 4 MHz would set the divisor to `2`. The SPI clock divisor, will be rounded up to the nearest power of two. This number can be calculated by dividing the MCU's clock speed by the desired SPI clock speed. For example, an MCU running at 8 MHz wanting to talk to an SPI device at 4 MHz would set the divisor to `2`.
#### Return Value #### Return Value :id=api-spi-start-return
`false` if the supplied parameters are invalid or the SPI peripheral is already in use, or `true`. `false` if the supplied parameters are invalid or the SPI peripheral is already in use, or `true`.
--- ---
### `spi_status_t spi_write(uint8_t data)` ### `spi_status_t spi_write(uint8_t data)` :id=api-spi-write
Write a byte to the selected SPI device. Write a byte to the selected SPI device.
#### Arguments #### Arguments :id=api-spi-write-arguments
- `uint8_t data` - `uint8_t data`
The byte to write. The byte to write.
#### Return Value #### Return Value :id=api-spi-write-return
`SPI_STATUS_TIMEOUT` if the timeout period elapses, or `SPI_STATUS_SUCCESS`. `SPI_STATUS_TIMEOUT` if the timeout period elapses, or `SPI_STATUS_SUCCESS`.
--- ---
### `spi_status_t spi_read(void)` ### `spi_status_t spi_read(void)` :id=api-spi-read
Read a byte from the selected SPI device. Read a byte from the selected SPI device.
#### Return Value #### Return Value :id=api-spi-read-return
`SPI_STATUS_TIMEOUT` if the timeout period elapses, or the byte read from the device. `SPI_STATUS_TIMEOUT` if the timeout period elapses, or the byte read from the device.
--- ---
### `spi_status_t spi_transmit(const uint8_t *data, uint16_t length)` ### `spi_status_t spi_transmit(const uint8_t *data, uint16_t length)` :id=api-spi-transmit
Send multiple bytes to the selected SPI device. Send multiple bytes to the selected SPI device.
#### Arguments #### Arguments :id=api-spi-transmit-arguments
- `const uint8_t *data` - `const uint8_t *data`
A pointer to the data to write from. A pointer to the data to write from.
- `uint16_t length` - `uint16_t length`
The number of bytes to write. Take care not to overrun the length of `data`. The number of bytes to write. Take care not to overrun the length of `data`.
#### Return Value #### Return Value :id=api-spi-transmit-return
`SPI_STATUS_TIMEOUT` if the timeout period elapses, `SPI_STATUS_ERROR` if some other error occurs, otherwise `SPI_STATUS_SUCCESS`. `SPI_STATUS_TIMEOUT` if the timeout period elapses, `SPI_STATUS_ERROR` if some other error occurs, otherwise `SPI_STATUS_SUCCESS`.
--- ---
### `spi_status_t spi_receive(uint8_t *data, uint16_t length)` ### `spi_status_t spi_receive(uint8_t *data, uint16_t length)` :id=api-spi-receive
Receive multiple bytes from the selected SPI device. Receive multiple bytes from the selected SPI device.
#### Arguments #### Arguments :id=api-spi-receive-arguments
- `uint8_t *data` - `uint8_t *data`
A pointer to the buffer to read into. A pointer to the buffer to read into.
- `uint16_t length` - `uint16_t length`
The number of bytes to read. Take care not to overrun the length of `data`. The number of bytes to read. Take care not to overrun the length of `data`.
#### Return Value #### Return Value :id=api-spi-receive-return
`SPI_STATUS_TIMEOUT` if the timeout period elapses, `SPI_STATUS_ERROR` if some other error occurs, otherwise `SPI_STATUS_SUCCESS`. `SPI_STATUS_TIMEOUT` if the timeout period elapses, `SPI_STATUS_ERROR` if some other error occurs, otherwise `SPI_STATUS_SUCCESS`.
--- ---
### `void spi_stop(void)` ### `void spi_stop(void)` :id=api-spi-stop
End the current SPI transaction. This will deassert the slave select pin and reset the endianness, mode and divisor configured by `spi_start()`. End the current SPI transaction. This will deassert the slave select pin and reset the endianness, mode and divisor configured by `spi_start()`.

32
docs/uart_driver.md
View File

@ -1,10 +1,10 @@
# UART Driver # UART Driver :id=uart-driver
The UART drivers used in QMK have a set of common functions to allow portability between MCUs. The UART drivers used in QMK have a set of common functions to allow portability between MCUs.
Currently, this driver does not support enabling hardware flow control (the `RTS` and `CTS` pins) if available, but may do so in future. Currently, this driver does not support enabling hardware flow control (the `RTS` and `CTS` pins) if available, but may do so in future.
## AVR Configuration ## AVR Configuration :id=avr-configuration
No special setup is required - just connect the `RX` and `TX` pins of your UART device to the opposite pins on the MCU: No special setup is required - just connect the `RX` and `TX` pins of your UART device to the opposite pins on the MCU:
@ -16,7 +16,7 @@ No special setup is required - just connect the `RX` and `TX` pins of your UART
|ATmega32A |`D1`|`D0`|*n/a*|*n/a*| |ATmega32A |`D1`|`D0`|*n/a*|*n/a*|
|ATmega328/P |`D1`|`D0`|*n/a*|*n/a*| |ATmega328/P |`D1`|`D0`|*n/a*|*n/a*|
## ChibiOS/ARM Configuration ## ChibiOS/ARM Configuration :id=arm-configuration
You'll need to determine which pins can be used for UART -- as an example, STM32 parts generally have multiple UART peripherals, labeled USART1, USART2, USART3 etc. You'll need to determine which pins can be used for UART -- as an example, STM32 parts generally have multiple UART peripherals, labeled USART1, USART2, USART3 etc.
@ -47,45 +47,45 @@ Configuration-wise, you'll need to set up the peripheral as per your MCU's datas
|`#define SD1_RTS_PIN` |The pin to use for RTS |`A12` | |`#define SD1_RTS_PIN` |The pin to use for RTS |`A12` |
|`#define SD1_RTS_PAL_MODE`|The alternate function mode for RTS |`7` | |`#define SD1_RTS_PAL_MODE`|The alternate function mode for RTS |`7` |
## Functions ## API :id=api
### `void uart_init(uint32_t baud)` ### `void uart_init(uint32_t baud)` :id=api-uart-init
Initialize the UART driver. This function must be called only once, before any of the below functions can be called. Initialize the UART driver. This function must be called only once, before any of the below functions can be called.
#### Arguments #### Arguments :id=api-uart-init-arguments
- `uint32_t baud` - `uint32_t baud`
The baud rate to transmit and receive at. This may depend on the device you are communicating with. Common values are 1200, 2400, 4800, 9600, 19200, 38400, 57600, and 115200. The baud rate to transmit and receive at. This may depend on the device you are communicating with. Common values are 1200, 2400, 4800, 9600, 19200, 38400, 57600, and 115200.
--- ---
### `void uart_write(uint8_t data)` ### `void uart_write(uint8_t data)` :id=api-uart-write
Transmit a single byte. Transmit a single byte.
#### Arguments #### Arguments :id=api-uart-write-arguments
- `uint8_t data` - `uint8_t data`
The byte to write. The byte to write.
--- ---
### `uint8_t uart_read(void)` ### `uint8_t uart_read(void)` :id=api-uart-read
Receive a single byte. Receive a single byte.
#### Return Value #### Return Value :id=api-uart-read-return
The byte read from the receive buffer. This function will block if the buffer is empty (ie. no data to read). The byte read from the receive buffer. This function will block if the buffer is empty (ie. no data to read).
--- ---
### `void uart_transmit(const uint8_t *data, uint16_t length)` ### `void uart_transmit(const uint8_t *data, uint16_t length)` :id=api-uart-transmit
Transmit multiple bytes. Transmit multiple bytes.
#### Arguments #### Arguments :id=api-uart-transmit-arguments
- `const uint8_t *data` - `const uint8_t *data`
A pointer to the data to write from. A pointer to the data to write from.
@ -94,11 +94,11 @@ Transmit multiple bytes.
--- ---
### `void uart_receive(char *data, uint16_t length)` ### `void uart_receive(char *data, uint16_t length)` :id=api-uart-receive
Receive multiple bytes. Receive multiple bytes.
#### Arguments #### Arguments :id=api-uart-receive-arguments
- `uint8_t *data` - `uint8_t *data`
A pointer to the buffer to read into. A pointer to the buffer to read into.
@ -107,10 +107,10 @@ Receive multiple bytes.
--- ---
### `bool uart_available(void)` ### `bool uart_available(void)` :id=api-uart-available
Return whether the receive buffer contains data. Call this function to determine if `uart_read()` will return data immediately. Return whether the receive buffer contains data. Call this function to determine if `uart_read()` will return data immediately.
#### Return Value #### Return Value :id=api-uart-available-return
`true` if the receive buffer length is non-zero. `true` if the receive buffer length is non-zero.