Skip to content

feat!: switch serialport library to serialport-napi-rs - #1942

Draft
Nerivec wants to merge 7 commits into
masterfrom
serialport-napi-rs
Draft

Nerivec wants to merge 7 commits into
masterfrom
serialport-napi-rs

Conversation

@Nerivec

@Nerivec Nerivec commented Nov 7, 2026 •

Copy link
Copy Markdown
Collaborator

Note

This will stay a draft until (at least) Node 22 EOL (Spring 2027), which will EOL 32-bit platforms, and allow us to move to this without too much trouble.

Important

This is experimental. We need a good amount of time for tests, and improvements. Feedback wanted!
We'll provide easier ways to test this once the basics are ironed out (currently requires building and overriding zigbee-herdsman locally).

Uses Rust-based NAPI-RS with tokio-serial instead of the old bindings-cpp from @serialport/stream.

The async binding API (though not yet finalized) is purposely kept very simple, as much as possible is delegated to tokio-serial, serialport & NAPI-RS, making it a "thin passthrough".

The current behavior is kept simple for several reasons, but mainly because this particular use is largely untested.
The simplistic initial approach will allow us to "strengthen" various aspects from actual observations rather than guesses; avoiding a crowded codebase for no good reason.
The TODO list at the bottom should cover these aspects in more details.

Worth noting that, as opposed to the previous package which published all binaries in one package, per NAPI-RS guidelines, this uses platform-specific optional dependencies; each installation, based on its platform, only gets the binary it needs.

Also worth noting that it is possible to override the binding's path with env NAPI_RS_NATIVE_LIBRARY_PATH, which skips the default logic ("detect platform then find binding in selected dependency").

Any review from Rust enthusiasts welcomed! https://github.com/Koenkk/serialport-napi-rs/blob/main/src/lib.rs
The current codebase is no more than a basic tokio loop (stream + command channel) with a basic napi-rs integration (a "make it work" sample). No doubt there is a lot of room for improvements, however, as mentioned above, we're looking for "real" improvements, rather than complicating the codebase for the sake of it; goal is to keep this a "thin passthrough", delegate to libraries.


Current tests (baremetal Debian 13 x64) show a rather drastic increase in performance:

hardware: TI CC2674P10 with CP210x, baudrate: 115200, flow: none
500+ samples (a whole-network startup+shutdown with TI stack)

before: mean=17.330 ms, median=16 ms, total=10069 ms
after:  mean=10.410 ms, median=8 ms,  total=6048 ms

delta:  mean=-6.921 ms, median=-7 ms, total=-4021 ms

hardware: Silabs MG24 with CP210x, baudrate: 460800, flow: none
50+ samples (a whole-network startup+shutdown with Silabs stack)

before: mean=15.250 ms, median=15 ms, total=854 ms
after:  mean=10.357 ms, median=9 ms,  total=580 ms

delta:  mean=-4.893 ms, median=-6 ms, total=-274 ms

Note: These numbers remain tiny in the "grand scheme" of things. However this should drastically reduce the various timeout issues observed in lower layers in "less reliable" setups.


TODO:

  • publish napi package & update package.json
  • fix surfaced ZNP test coverage lacks
  • update ZoH for compatibility
  • real-world tests
    • basics (open/receive/write/close)
    • behavior in case of "soft" error
    • behavior in case of fatal error
    • behavior under interference
    • behavior under excessive port load
    • behavior under excessive node event loop load
    • behavior under node event loop stall
  • platform-specific tests of above point
    • aarch64-apple-darwin
    • aarch64-linux-android
    • aarch64-unknown-linux-gnu
    • aarch64-unknown-linux-musl
    • aarch64-pc-windows-msvc
    • x86_64-apple-darwin
    • x86_64-pc-windows-msvc
    • x86_64-unknown-linux-gnu
    • x86_64-unknown-linux-musl

CC: @andrei-lazarov @chris-1243 @thk-socal @manup @kirovilya @Gnarfoz


Please respect the AI policy for any report/post.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant