DeviceTree Formatter

[innovaker]

We're increasingly in need of a DeviceTree formatter. We're looking for a volunteer to implement one.

It must ...

• format these files:
  • .dts
  • .dtsi
  • .overlay
  • .keymap
• run in:
  • CLI
  • GitHub workflows
  • VS Code
• support all platforms used by ZMK developers.

It should ...

• not affect the format of the bindings map i.e. contents of bindings = < ... >;

It may ...

• copy/emulate conventions found in existing DT files.
• be generic enough to use beyond ZMK?

See relevant conversations:

• https://discord.com/channels/719497620560543766/719565084208398406/794552358209191969
• https://discord.com/channels/719497620560543766/719565084208398406/795994278810746927
• https://discord.com/channels/719497620560543766/719565084208398406/796067132441100316
• https://discord.com/channels/719497620560543766/719565084208398406/796101098536173598

[innovaker]

Please reply to this issue if you start work on it so that we can assign the issue to you (avoids duplicate efforts).

[joelspadin]

Given https://github.com/zmkfirmware/zmk/pull/568, a Prettier plugin seems like a convenient way to implement this.

Ignoring bindings properties could be done by implementing a // prettier-ignore comment and just prefixing bindings in keymaps with it. You could additionally try to automatically ignore bindings, but you'd want to still support the ignore comment for future features like per-key RGB color maps, etc. that the formatter doesn't yet know about.

I've written a mostly complete DT parser that runs in NodeJS at https://github.com/joelspadin/tree-sitter-devicetree. It is built on https://tree-sitter.github.io/tree-sitter/. Here is a project that uses it as an example: https://github.com/joelspadin/zmk-tools/blob/main/src/Parser.ts. (To my knowledge the only thing not yet supported in the parser is labels inside property values.)

[innovaker]

To anyone who reads this, we're still looking for a volunteer to spearhead this issue.

If you're a developer wishing to contribute to ZMK without touching C/embedded, this might be just the ticket.

[nickcoutsos]

Hi!

I've been doing a little work on this for my own project with the help of tree-sitter-devicetree and I don't know if I can satisfy the requirements describe above, but I'd be interested in some discussion and knowing if the ZMK maintainers have any kind of preferred style for formatting devicetree code.

Here are the basic rules I came up with for myself.

Indentation

• Contents of a devicetree node are indented 4 spaces for every level of their depth
• No indentation or formatting is applied to the contents of a multi-line integer_cells node (this also applies to comments if they're put inside the node... I'm not sure if this is technically correct devicetree syntax but I've seen it used in keymaps)
  • As an aside, I have a layout definition that lets me format a bindings list according to the keyboard's layout
  • I also have some code to auto-generate the layout definition from the keyboard's matrix-transform but this isn't that fleshed out
• Macro bindings are formatted like

  bindings =
      <foo>,
      <bar>;

  I know the ZMK docs presents a different formatting here. That isn't my preferred style but I don't have a problem implementing that whenever I can get around to it... is that considered "standard" for the purposes a formatter?

I picked 4-space tabs because... if I have to force something on people it seems like a safe bet. But it's gotten me thinking about the ways people make these configurations portable. I'm not a vim user but it might be simple enough to look out for a modeline to get the preferred tab size (I'm reading the file already) or even to check for an .editorconfig.

Spacing

• Adjacent nodes of the same type (i.e. groups of properties, or includes, or defines) have no blank lines between them
• Adjacent nodes of different types (like a compatible = "zmk,combos"; property followed by a combo node) and adjacent devicetree nodes are separated by one blank line
• Multi-line property nodes (layer and macro bindings) get an extra blank line before the next node even if its another property)

As is frequently the case, this is what I came up with by experimentation and it's more than likely I'm missing some more critical edge cases due to my ignorance of devicetree and maybe more complex keymaps. I haven't even looked at applying it to board/shield definitions yet.

[jakenvac]

I understand that it makes sense to structure keymaps as DeviceTree files under the hood, but is this really a good way for the end user to create their keymaps? Ive built a preprocessor that allows you to create your keymaps in typescript programmatically and outputs the relevant DTS. Would this be something the zmk project is interested in? Right now its very tailored to my use but I'd be happy to make it more generic and make the repo public/contribute the code to zmk

Sorry for bad formatting/grammar. Currently on mobile.

[ELLIOTTCABLE]

@jakenvac Personally, I prefer declarative formats (see Dhall's homepage and documentation for some good arguments there), but I wouldn't mind seeing your work published. Sounds like it'd be useful in some cases. (=

[joebonneau]

I landed here from a search for a devicetree formatter and came across dtsfmt. I don't know if the maintainer would be interested in contributing to ZMK directly, but I wanted to bring it to the group's attention.