From 492e421ec73b889531631569463e84f41eec017d Mon Sep 17 00:00:00 2001 From: Joel Spadin Date: Sat, 18 Nov 2023 19:49:49 -0600 Subject: [PATCH] docs: Document behavior name length limit Added a section to the new behavior guide to document that the names of behaviors invoked on the peripheral side of a split must be at most 8 characters long. --- docs/docs/development/new-behavior.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/docs/docs/development/new-behavior.md b/docs/docs/development/new-behavior.md index 129ba324817b..59872963f10f 100644 --- a/docs/docs/development/new-behavior.md +++ b/docs/docs/development/new-behavior.md @@ -380,7 +380,20 @@ For the purpose of this section, we will discuss the structure of `app/dts/behav }; ``` -The format of a behavior's `.dtsi` file is identical to declaring an instance of the behavior in a user's keymap. The only major difference is that the value `/omit-if-no-ref/` should be placed adjacent to the name of the behavior, as seen in line 11 of the `gresc` example. +The format of a behavior's `.dtsi` file is identical to declaring an instance of the behavior in a user's keymap. The only major difference is that the value `/omit-if-no-ref/` should be placed adjacent to the label and name of the behavior, as seen in line 11 of the `gresc` example. + +:::caution + +If your behavior has its [`locality`](#api-structure) property set to anything other than `BEHAVIOR_LOCALITY_CENTRAL`, then the name of the node must be at most 8 characters long, or it will fail to be invoked on the peripheral half of a split keyboard. + +In the above example, `grave_escape` is too long, so it would need to be shortened, e.g. + +```dts +// Behavior can be invoked on peripherals, so name must be <= 8 characters. +/omit-if-no-ref/ gresc: gresc { ... }; +``` + +::: After creating the `.dtsi` from above, update `app/dts/behaviors.dtsi` to include your newly predefined behavior instance, making it accessible by the devicetree.