151 lines
4.9 KiB
C
151 lines
4.9 KiB
C
/* ----------------------------------------------------------------------------
|
|
* Copyright (c) 2013 Ben Blazak <benblazak.dev@gmail.com>
|
|
* Released under The MIT License (see "doc/licenses/MIT.md")
|
|
* Project located at <https://github.com/benblazak/ergodox-firmware>
|
|
* ------------------------------------------------------------------------- */
|
|
|
|
/** description
|
|
* The USB interface
|
|
*
|
|
* Prefixes: `usb__` `usb__kb__`
|
|
*/
|
|
|
|
|
|
#ifndef ERGODOX_FIRMWARE__FIRMWARE__LIB__USB__H
|
|
#define ERGODOX_FIRMWARE__FIRMWARE__LIB__USB__H
|
|
// ----------------------------------------------------------------------------
|
|
// ----------------------------------------------------------------------------
|
|
|
|
|
|
#include <stdbool.h>
|
|
#include <stdint.h>
|
|
|
|
// ----------------------------------------------------------------------------
|
|
|
|
// --- general ---
|
|
|
|
uint8_t usb__init (void);
|
|
bool usb__is_configured (void);
|
|
|
|
// --- keyboard ---
|
|
|
|
uint8_t usb__kb__set_key (bool pressed, uint8_t keycode);
|
|
bool usb__kb__read_key (uint8_t keycode);
|
|
bool usb__kb__read_led (char led);
|
|
uint8_t usb__kb__send_report (void);
|
|
|
|
|
|
// ----------------------------------------------------------------------------
|
|
// ----------------------------------------------------------------------------
|
|
#endif // ERGODOX_FIRMWARE__FIRMWARE__LIB__USB__H
|
|
|
|
|
|
|
|
// ============================================================================
|
|
// === documentation ==========================================================
|
|
// ============================================================================
|
|
|
|
|
|
// ----------------------------------------------------------------------------
|
|
// general --------------------------------------------------------------------
|
|
|
|
// === usb__init() ===
|
|
/** functions/usb__init/description
|
|
* Initialize USB for this device
|
|
*
|
|
* Returns:
|
|
* - success: `0`
|
|
* - failure: [other]
|
|
*
|
|
* Notes:
|
|
* - Should be called exactly once by `main()`, and nothing else USB related
|
|
* should be done until `usb__configured` is `true`
|
|
*/
|
|
|
|
// === usb__is_configured ===
|
|
/** functions/usb__is_configured/description
|
|
* Check whether this device has been configured by the host
|
|
*
|
|
* Returns:
|
|
* - `true`: if the device has been configured
|
|
* - `false`: if the device has not been configured
|
|
*
|
|
* Notes:
|
|
* - Should return `true` before calling any function other than `usb__init()`
|
|
*/
|
|
|
|
|
|
// ----------------------------------------------------------------------------
|
|
// keyboard -------------------------------------------------------------------
|
|
|
|
// === usb__kb__set_key() ===
|
|
/** functions/usb__kb__set_key/description
|
|
* Set the given keycode as 'pressed' ('on') or 'released' ('off') (device
|
|
* side)
|
|
*
|
|
* Arguments:
|
|
* - `pressed`: whether to set the keycode 'on' (`true`) or 'off' (`false`)
|
|
* - `keycode`: the keycode to set
|
|
*
|
|
* Returns:
|
|
* - success: `0`
|
|
* - failure: status code (unspecified, nonzero)
|
|
*
|
|
* Notes:
|
|
* - Setting a keycode 'on' or 'off' does not send the report, and the host
|
|
* will not know the state of the keycode until the report is sent. If a key
|
|
* is set 'on' then 'off' without sending the report in between, the host
|
|
* will know nothing about it.
|
|
*/
|
|
|
|
// === usb__kb__read_key() ===
|
|
/** functions/usb__kb__read_key/description
|
|
* Check whether the given keycode is set to 'on' (device side)
|
|
*
|
|
* Arguments:
|
|
* - `keycode`: the keycode to check
|
|
*
|
|
* Returns:
|
|
* - `false`: if the state of the given keycode is set to 'off'
|
|
* - `true`: if the state of the given keycode is set to 'on'
|
|
*
|
|
* Notes:
|
|
* - The fact that a given keycode is set to some value here does not mean that
|
|
* the host knows about it. The host will only know the current state of the
|
|
* keycodes if the report has been sent since the last change.
|
|
*/
|
|
|
|
// === usb__kb__read_led() ===
|
|
/** functions/usb__kb__read_led/description
|
|
* Check whether the given (logical) LED is set to 'on' (host side)
|
|
*
|
|
* Arguments:
|
|
* - `led`:
|
|
* - `N`: numlock
|
|
* - `C`: capslock
|
|
* - `S`: scroll lock
|
|
* - `O`: compose
|
|
* - `K`: kana
|
|
*
|
|
* Returns:
|
|
* - `false`: if the state of the given (logical) LED is set to 'off'
|
|
* - `true`: if the state of the given (logical) LED is set to 'on'
|
|
*
|
|
* Notes:
|
|
* - No data is actually exchanged with the host by this function, but
|
|
* maintaining the state of these (logical) LEDs (and informing the device
|
|
* when they change) is the host's responsibility. The device only keeps
|
|
* track of what the host tells it.
|
|
*/
|
|
|
|
// === usb__kb__send_report() ===
|
|
/** functions/usb__kb__send_report/description
|
|
* Send the USB report to the host (update the host on the state of the
|
|
* keycodes)
|
|
*
|
|
* Returns:
|
|
* - success: `0`
|
|
* - failure: status code (unspecified, nonzero)
|
|
*/
|
|
|