From 63df8aaf50380d9ea5cd7462e35173554a638130 Mon Sep 17 00:00:00 2001 From: Florian Didron Date: Fri, 22 Aug 2025 12:27:10 +0700 Subject: [PATCH] chore: add more comments --- drivers/sensors/navigator.c | 3 +++ drivers/sensors/navigator.h | 3 +++ drivers/sensors/navigator_trackball.c | 18 ++++++++++++++++++ drivers/sensors/navigator_trackball.h | 4 +++- drivers/sensors/navigator_trackpad.c | 3 +++ drivers/sensors/navigator_trackpad.h | 3 +++ 6 files changed, 33 insertions(+), 1 deletion(-) diff --git a/drivers/sensors/navigator.c b/drivers/sensors/navigator.c index d82fa980a4..90ca16709a 100644 --- a/drivers/sensors/navigator.c +++ b/drivers/sensors/navigator.c @@ -1,3 +1,6 @@ +// Copyright 2025 ZSA Technology Labs, Inc +// SPDX-License-Identifier: GPL-2.0-or-later + #include "quantum.h" #include "navigator.h" diff --git a/drivers/sensors/navigator.h b/drivers/sensors/navigator.h index b1e0db17d0..73e809715b 100644 --- a/drivers/sensors/navigator.h +++ b/drivers/sensors/navigator.h @@ -1,3 +1,6 @@ +// Copyright 2025 ZSA Technology Labs, Inc +// SPDX-License-Identifier: GPL-2.0-or-later + #pragma once #ifndef NAVIGATOR_SCROLL_DIVIDER #define NAVIGATOR_SCROLL_DIVIDER 10 diff --git a/drivers/sensors/navigator_trackball.c b/drivers/sensors/navigator_trackball.c index e1b58c8d7f..b6114625e5 100644 --- a/drivers/sensors/navigator_trackball.c +++ b/drivers/sensors/navigator_trackball.c @@ -1,3 +1,11 @@ +// Copyright 2025 ZSA Technology Labs, Inc +// SPDX-License-Identifier: GPL-2.0-or-later + +// This is the QMK driver for the Navigator Trackball. It is comprised of two ICs: +// 1. The sci18is606 is a i2c to spi bridge that converts the i2c protocol to the spi protocol. It allows the trackball to +// be plugged using the TRRS jack used by ZSA keyboards or any other split keyboard. +// 2. The paw3805ek is a high-speed motion detection sensor. It is used to detect the motion of the trackball. + #include "i2c_master.h" #include "navigator_trackball.h" #include @@ -19,6 +27,7 @@ uint8_t trackball_init = 0; deferred_token callback_token = 0; +// The sequence of commands to configure and boot the paw3805ek sensor. paw3805ek_reg_seq_t paw3805ek_configure_seq[] = { {0x06, 0x80}, // Software reset {0x00, 0x00}, // Request the sensor ID @@ -32,14 +41,17 @@ paw3805ek_reg_seq_t paw3805ek_configure_seq[] = { {0x09 | WRITE_REG_BIT, 0x00}, // Enable the write protection }; +// A wrapper function for i2c_transmit that adds the address of the bridge chip to the data. i2c_status_t sci18is606_write(uint8_t *data, uint8_t length) { return i2c_transmit(NAVIGATOR_TRACKBALL_ADDRESS, data, length, NAVIGATOR_TRACKBALL_TIMEOUT); } +// A wrapper function for i2c_receive that adds the address of the bridge chip to the data. i2c_status_t sci18is606_read(uint8_t *data, uint8_t length) { return i2c_receive(NAVIGATOR_TRACKBALL_ADDRESS, data, length, NAVIGATOR_TRACKBALL_TIMEOUT); } +// A wrapper function that allows to write and optionally read from the bridge chip. i2c_status_t sci18is606_spi_tx(uint8_t *data, uint8_t length, bool read) { i2c_status_t status = sci18is606_write(data, length); wait_us(length * 15); @@ -53,6 +65,7 @@ i2c_status_t sci18is606_spi_tx(uint8_t *data, uint8_t length, bool read) { return status; } +// Configure the bridge chip to enable SPI mode. i2c_status_t sci18is606_configure(void) { uint8_t spi_conf[2] = {SCI18IS606_CONF_SPI, SCI18IS606_CONF}; i2c_status_t status = sci18is606_write(spi_conf, 2); @@ -119,6 +132,7 @@ bool paw3805ek_set_cpi(void) { {0x09 | WRITE_REG_BIT, 0x00}, // Enable the write protection }; + // Run the spi sequence to configure the cpi. for (uint8_t i = 0; i < sizeof(cpi_reg_seq) / sizeof(paw3805ek_reg_seq_t); i++) { uint8_t buf[3]; buf[0] = NCS_PIN; @@ -132,6 +146,7 @@ bool paw3805ek_set_cpi(void) { return true; } +// Run the paw3805ek configuration sequence. bool paw3805ek_configure(void) { for (uint8_t i = 0; i < sizeof(paw3805ek_configure_seq) / sizeof(paw3805ek_reg_seq_t); i++) { uint8_t buf[3]; @@ -153,6 +168,7 @@ bool paw3805ek_configure(void) { return true; } +// Assert the CS pin to read the motion register. bool paw3805ek_has_motion(void) { uint8_t motion[3] = {0x01, 0x02, 0x00}; if (sci18is606_spi_tx(motion, 3, true) != I2C_STATUS_SUCCESS) { @@ -161,6 +177,7 @@ bool paw3805ek_has_motion(void) { return motion[1] & 0x80; } +// Read the motion data from the paw3805ek sensor. void paw3804ek_read_motion(report_mouse_t *mouse_report) { #ifdef MOUSE_EXTENDED_REPORT uint8_t delta_x_l[2] = {0x01, 0x03}; @@ -201,6 +218,7 @@ void paw3804ek_read_motion(report_mouse_t *mouse_report) { #endif } +// Deffered execution callback that periodically checks for motion. uint32_t sci18is606_read_callback(uint32_t trigger_time, void *cb_arg) { if (!trackball_init) { navigator_trackball_device_init(); diff --git a/drivers/sensors/navigator_trackball.h b/drivers/sensors/navigator_trackball.h index 2638edc6da..f364c583aa 100644 --- a/drivers/sensors/navigator_trackball.h +++ b/drivers/sensors/navigator_trackball.h @@ -1,3 +1,6 @@ +// Copyright 2025 ZSA Technology Labs, Inc +// SPDX-License-Identifier: GPL-2.0-or-later + #pragma once #include #include @@ -25,7 +28,6 @@ #define SCI18IS606_GET_ID 0xFE #define WRITE_REG_BIT 0x80 - /* The PAW3805EK datasheet suggests the following CPI values for the X and Y axes: CPI X-axis Y-axis diff --git a/drivers/sensors/navigator_trackpad.c b/drivers/sensors/navigator_trackpad.c index 99dcef7c86..b9e0cebaad 100644 --- a/drivers/sensors/navigator_trackpad.c +++ b/drivers/sensors/navigator_trackpad.c @@ -1,3 +1,6 @@ +// Copyright 2025 ZSA Technology Labs, Inc +// SPDX-License-Identifier: GPL-2.0-or-later + #include #include #include diff --git a/drivers/sensors/navigator_trackpad.h b/drivers/sensors/navigator_trackpad.h index 4fd2a81212..0ca548ed77 100644 --- a/drivers/sensors/navigator_trackpad.h +++ b/drivers/sensors/navigator_trackpad.h @@ -1,3 +1,6 @@ +// Copyright 2025 ZSA Technology Labs, Inc +// SPDX-License-Identifier: GPL-2.0-or-later + #pragma once #include #include