feat(endpoints): add concept of no endpoint

This adds ZMK_TRANSPORT_NONE, which can be set as the preferred
endpoint transport if you wish to prevent the keyboard from sending any
output. More usefully, it also is used to indicate that the preferred
endpoint is not available and it could not fall back to an available
one. To go along with this, many endpoint functions are renamed for
consistency, and a few new functions are added:

- zmk_endpoint_get_preferred_transport() returns the value that was set
  with zmk_endpoint_set_preferred_transport().

- zmk_endpoint_get_preferred() returns the endpoint that will be used
  if it is available. This endpoint always has the same transport as
  zmk_endpoint_get_preferred_transport().

- zmk_endpoint_is_connected() is a shortcut to check if the keyboard is
  actually connected to an endpoint.

This change is based on #2572 but without the option to disable endpoint
fallback. It does refactor code to allow adding that feature later.

Author: joelspadin

app/boards/lowprokb/corneish_zen/widgets/output_status.c

@@ -45,7 +45,7 @@ struct output_status_state {
 
 static struct output_status_state get_state(const zmk_event_t *_eh) {
     return (struct output_status_state){
-        .selected_endpoint = zmk_endpoints_selected(),
+        .selected_endpoint = zmk_endpoint_get_selected(),
         .active_profile_connected = zmk_ble_active_profile_is_connected(),
         .active_profile_bonded = !zmk_ble_active_profile_is_open(),
     };

app/boards/shields/nice_view/widgets/status.c

@@ -261,7 +261,7 @@ static void output_status_update_cb(struct output_status_state state) {
 
 static struct output_status_state output_status_get_state(const zmk_event_t *_eh) {
     struct output_status_state state = {
-        .selected_endpoint = zmk_endpoints_selected(),
+        .selected_endpoint = zmk_endpoint_get_selected(),
         .active_profile_index = zmk_ble_active_profile_index(),
         .active_profile_connected = zmk_ble_active_profile_is_connected(),
         .active_profile_bonded = !zmk_ble_active_profile_is_open(),

app/include/zmk/endpoints.h

@@ -14,6 +14,8 @@
  */
 #define ZMK_ENDPOINT_STR_LEN 10
 
+#define ZMK_ENDPOINT_NONE_COUNT 1
+
 #ifdef CONFIG_ZMK_USB
 #define ZMK_ENDPOINT_USB_COUNT 1
 #else
@@ -33,7 +35,8 @@
  * Note that this value may change between firmware versions, so it should not
  * be used in any persistent storage.
  */
-#define ZMK_ENDPOINT_COUNT (ZMK_ENDPOINT_USB_COUNT + ZMK_ENDPOINT_BLE_COUNT)
+#define ZMK_ENDPOINT_COUNT                                                                         \
+    (ZMK_ENDPOINT_NONE_COUNT + ZMK_ENDPOINT_USB_COUNT + ZMK_ENDPOINT_BLE_COUNT)
 
 bool zmk_endpoint_instance_eq(struct zmk_endpoint_instance a, struct zmk_endpoint_instance b);
 
@@ -57,21 +60,53 @@ int zmk_endpoint_instance_to_str(struct zmk_endpoint_instance endpoint, char *st
 int zmk_endpoint_instance_to_index(struct zmk_endpoint_instance endpoint);
 
 /**
- * Sets the preferred endpoint transport to use. (If the preferred endpoint is
- * not available, a different one may automatically be selected.)
+ * Sets the preferred endpoint transport to use.
+ *
+ * If the preferred endpoint is not available, zmk_endpoint_get_selected() may
+ * automatically fall back to another transport.
+ */
+int zmk_endpoint_set_preferred_transport(enum zmk_transport transport);
+
+enum zmk_transport zmk_endpoint_get_preferred_transport(void);
+
+/**
+ * If the preferred endpoint transport is USB, sets it to BLE, else sets it to USB.
+ */
+int zmk_endpoint_toggle_preferred_transport(void);
+
+/**
+ * Gets the endpoint instance that will be preferred if it is connected.
+ */
+struct zmk_endpoint_instance zmk_endpoint_get_preferred(void);
+
+/**
+ * Gets the endpoint instance that is currently in use.
+ *
+ * This may differ from zmk_endpoint_get_preferred(), for example if the preferred
+ * endpoint is not connected, then this will return an instance for ZMK_TRANSPORT_NONE.
  */
-int zmk_endpoints_select_transport(enum zmk_transport transport);
-int zmk_endpoints_toggle_transport(void);
+struct zmk_endpoint_instance zmk_endpoint_get_selected(void);
 
 /**
- * Gets the currently-selected endpoint.
+ * Returns whether the keyboard is connected to an endpoint.
+ *
+ * This is equivalent to zmk_endpoint_get_selected().transport != ZMK_TRANSPORT_NONE
  */
-struct zmk_endpoint_instance zmk_endpoints_selected(void);
+bool zmk_endpoint_is_connected(void);
 
-int zmk_endpoints_send_report(uint16_t usage_page);
+/**
+ * Sends the HID report for the given usage page to the selected endpoint.
+ */
+int zmk_endpoint_send_report(uint16_t usage_page);
 
 #if IS_ENABLED(CONFIG_ZMK_POINTING)
-int zmk_endpoints_send_mouse_report();
+/**
+ * Sends the HID mouse report to the selected endpoint.
+ */
+int zmk_endpoint_send_mouse_report();
 #endif // IS_ENABLED(CONFIG_ZMK_POINTING)
 
-void zmk_endpoints_clear_current(void);
+/**
+ * Clears all HID reports for the selected endpoint.
+ */
+void zmk_endpoint_clear_reports(void);

app/include/zmk/endpoints_types.h

@@ -10,6 +10,7 @@
  * The method by which data is sent.
  */
 enum zmk_transport {
+    ZMK_TRANSPORT_NONE,
     ZMK_TRANSPORT_USB,
     ZMK_TRANSPORT_BLE,
 };

app/src/behaviors/behavior_outputs.c

@@ -60,11 +60,11 @@ static int on_keymap_binding_pressed(struct zmk_behavior_binding *binding,
                                      struct zmk_behavior_binding_event event) {
     switch (binding->param1) {
     case OUT_TOG:
-        return zmk_endpoints_toggle_transport();
+        return zmk_endpoint_toggle_preferred_transport();
     case OUT_USB:
-        return zmk_endpoints_select_transport(ZMK_TRANSPORT_USB);
+        return zmk_endpoint_set_preferred_transport(ZMK_TRANSPORT_USB);
     case OUT_BLE:
-        return zmk_endpoints_select_transport(ZMK_TRANSPORT_BLE);
+        return zmk_endpoint_set_preferred_transport(ZMK_TRANSPORT_BLE);
     default:
         LOG_ERR("Unknown output command: %d", binding->param1);
     }

app/src/display/widgets/output_status.c

@@ -22,25 +22,43 @@ static sys_slist_t widgets = SYS_SLIST_STATIC_INIT(&widgets);
 
 struct output_status_state {
     struct zmk_endpoint_instance selected_endpoint;
+    enum zmk_transport preferred_transport;
     bool active_profile_connected;
     bool active_profile_bonded;
 };
 
 static struct output_status_state get_state(const zmk_event_t *_eh) {
-    return (struct output_status_state){.selected_endpoint = zmk_endpoints_selected(),
-                                        .active_profile_connected =
-                                            zmk_ble_active_profile_is_connected(),
-                                        .active_profile_bonded = !zmk_ble_active_profile_is_open()};
-    ;
+    return (struct output_status_state){
+        .selected_endpoint = zmk_endpoint_get_selected(),
+        .preferred_transport = zmk_endpoint_get_preferred_transport(),
+        .active_profile_connected = zmk_ble_active_profile_is_connected(),
+        .active_profile_bonded = !zmk_ble_active_profile_is_open(),
+    };
 }
 
 static void set_status_symbol(lv_obj_t *label, struct output_status_state state) {
     char text[20] = {};
 
-    switch (state.selected_endpoint.transport) {
+    enum zmk_transport transport = state.selected_endpoint.transport;
+    bool connected = transport != ZMK_TRANSPORT_NONE;
+
+    // If we aren't connected, show what we're *trying* to connect to.
+    if (!connected) {
+        transport = state.preferred_transport;
+    }
+
+    switch (transport) {
+    case ZMK_TRANSPORT_NONE:
+        strcat(text, LV_SYMBOL_CLOSE);
+        break;
+
     case ZMK_TRANSPORT_USB:
         strcat(text, LV_SYMBOL_USB);
+        if (!connected) {
+            strcat(text, " " LV_SYMBOL_CLOSE);
+        }
         break;
+
     case ZMK_TRANSPORT_BLE:
         if (state.active_profile_bonded) {
             if (state.active_profile_connected) {