feat(behaviors): Add a send string behavior

[joelspadin]

This adds the following:

• A character map driver API, which maps Unicode code points to behavior bindings.
• A zmk,character-map driver which implements this API. This driver is designed for ROM efficiency, and it sends every value defined in the map to one behavior and passes any code point not in the map through to another. (A more flexible implementation that allows for a unique behavior binding per character could be added later if necessary.)
• A zmk,send-string behavior, which users can define and bind to their keymaps to send strings.
• A zmk_send_string() function, which queues the necessary behaviors to type a UTF-8 string. This is separated from the send string behavior since it could be used for other features such as Unicode key sequences, behaviors that print dynamic messages, etc.

[caksoylar]

I will do a second pass later but the docs look great, thank you for the effort you put into it! One suggestion I'd have is to put a pointer in the macros page pointing to this behavior for string sending purposes, similar to the pointer we have for modifier functions.

[jhorology]

I've been waiting for this function. If there is a printf-style format function, I would be more than happy. Once I read the zephyr's code related to printf, It's difficult to understand to me.

[joelspadin]

One suggestion I'd have is to put a pointer in the macros page pointing to this behavior for string sending purposes, similar to the pointer we have for modifier functions.

Good idea. I'll add that.

I've been waiting for this function. If there is a printf-style format function, I would be more than happy. Once I read the zephyr's code related to printf, It's difficult to understand to me.

You could use the zmk_send_string() function with printf by printing to a string buffer and then sending that to the function, for example:

struct zmk_send_string_config config = {
    .character_map = DEVICE_DT_GET(DT_CHOSEN(zmk_character_map)),
    .wait_ms = CONFIG_ZMK_SEND_STRING_DEFAULT_WAIT_MS,
    .tap_ms = CONFIG_ZMK_SEND_STRING_DEFAULT_TAP_MS,
};

char string[32];
snprintf(string, sizeof(string), "Battery level is %u%%", zmk_battery_state_of_charge());

zmk_send_string(&config, position, string);

[joelspadin]

I added some macros for creating the config structs, so the code example above can now be simplified to

ZMK_BUILD_ASSERT_CHARACTER_MAP_CHOSEN();
...

char string[32];
snprintf(string, sizeof(string), "Battery level is %u%%", zmk_battery_state_of_charge());

zmk_send_string(&ZMK_SEND_STRING_CONFIG_DEFAULT, position, string);

[caksoylar]

LGTM from a docs perspective 👍

[minhe7735]

pr broken because of this? 690bc1b

[dryqin]

Will be great if this gets merged!

[joelspadin]

Rebased and fixed everything to work with current ZMK.

[prez]

I've been eagerly waiting for this for almost a year now. Is there any chance we'll get to see this merged soon? Thank you!

[joelspadin]

Rebased and cleaned up a few things. Added a workaround to repurpose \f as the new line character, since \n gets inserted into the generated .h file as an actual line break and breaks the build.

[joelspadin]

It looks like while \" and \\ do work correctly in generated C code, they break the generated cmake code... I'll see if I can contribute a patch to Zephyr to fix that.

[joelspadin]

Removed the \f workaround. This now requires the fix at zephyrproject-rtos/zephyr#78433 to use any of \" \\ \r \n in a string.

[joelspadin]

The fact that the previous version still built despite passing a uint32_t to the first parameter of zmk_behavior_queue_add, which had been changed from a uint32_t to a pointer, is a bit concerning...

[joelspadin]

We will need to cherry-pick zephyrproject-rtos/zephyr@c82799b and zephyrproject-rtos/zephyr@6edefd8 for all strings to work correctly.

[caksoylar]

Can you add an entry to https://deploy-preview-1893--zmk.netlify.app/docs/keymaps/behaviors#user-defined-behaviors as well?

[zhiayang]

Has this been tested to work correctly for "super-long" strings (>200 chars)? In my experience it seems like something gets stuck at around 100-150 characters, even if I set the queue size to 256.

I got it to work (locally) by queueing the zmk_behavior_queue_add press & release calls into a work queue with an additional k_sleep after sending one character. Suboptimal, but I don't really have time to probe further here.

[joelspadin]

I have not tested it with sizes that large, but the behavior you described seems expected given how it currently works. The queue size needs to be 2x the number of characters, because each character has a press and a release. If you want to send 200 characters, you will need a queue size of 400.

I do think the way it works currently is suboptimal, but the only better solution I can think of is to add a way to insert a message into the behavior queue which does not trigger a behavior press/release but instead calls a callback so a behavior can queue another chunk of items.

[ssbb]

Should it be KERNEL_INIT_PRIORITY_DEFAULT instead of APPLICATION_INIT_PRIORITY? All the existing behaviors using KERNEL_INIT_PRIORITY_DEFAULT now and it fails when trying to call send-string behavior from them (because higher priority depends on lower).