Skip to content

Latest commit

 

History

History
48 lines (30 loc) · 2.71 KB

README.md

File metadata and controls

48 lines (30 loc) · 2.71 KB

Haystack Command Encoder

What is it?

It is a library that adds a layer of safety to an existing serial interface so that end-users can handle device connections by themself plug-and-play style.
Complements Haystack Command Decoder

Why do we need this?

UART is fine when used by professionals, but for end-users, there are so many things that can go wrong.
Users can, and will, plug UART devices together and then launch a totally unrelated application from the host device resulting in unexpected or unpredictable behaviors.

The issue stemmed from the UART itself.
Unlike USB devices, which have descriptors, UART devices do not have a standard or a convention to provide distinguishing between devices. This library was designed to addresses this shortcoming. Simply put, the library brings USB VID/PID equivalent to the UART devices.

More explanations, please.

The author wrote an article about this library at Slime Systems' website.

How does this library works, anyway?

The library works by prefixing each command with a 128-bit key. The number was deliberately chosen because it is long enough for everyone. And provide sufficient collision resistance against all currently utilized UART protocols.

Compatibilities

Although originally designed for UART on STM8, the library is agnostic to underlying serial protocols and ISAs.

The library will work anywhere as long as the standard C language works.
SDCC takes first-class priority.

It should run fine on AVR, Arm Cortex-M, PIC, MCS-51, etc. if not, please open an issue on GitHub, you just found a bug.

The compatibility also spans beyond UART, the library works on any 8-bit serial interface.

How to use this?

This is a very tiny software, it is bothersome to write a formal document for it. Plus, who would read it anyway?
Please proceed to the article for an informal guide, and if you need more info, looking into the source code would be a very quick grok.

Or you can also see a working example in another GitHub repository.
You may also want to see the complementary library, Haystack Command Decoder.

License

Haystack Command Encoder is released under the BSD 3-Clause License. 🎉