Commandline client and client library for the twinkl protocol
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Sebastian 8d8cd1c883 Added new default animation for alma 4 years ago
animations Added new default animation for alma 4 years ago
include Fixed error handling for client lib 5 years ago
twinkl@2035657f8a Priority was never set in outgoing packets 5 years ago
.gitignore Added python2 wrapper for 5 years ago
.gitmodules Initial commit 5 years ago
Makefile Fixed error handling for client lib 5 years ago Fixed error handling for client lib 5 years ago
main.c Fixed error handling for client lib 5 years ago
message_wrapper.c Added more functions to manage twinkl messages to the shared library 5 years ago
twinklsocket.c Fixed error handling for client lib 5 years ago



git clone
cd twinkl-client
git submodule init
git submodule update


twinkle-client <twinkl server> <priority>
  • twinkle server: The ip or hostname of the twinkl-server
  • priority: Priority of your packet 0 is highest 7 is lowest

twinkl-client reads a list of channel value pairs from stdin. One pair per line in the format <channel> : <value>. Channels range from 0 to 511 while values range from 0 to 255. Both can be entered in decimal or hexadecimal (prefix with 0x). An empty line sends the twinkl packet containing all values since the last empty line. An EOF (Ctrl-D) also sends the twinkel packet and terminates the client.

Only channels that have been assigned a value before sending the packet will be reserved for usage by your priority level. This implies that if you want a channel to stay at 0 without a lower priority level being able to override it you have to set it to 0 in every packet you send. It is also a good Idea to send an empty packet (newline directly followed by a EOF) before killing the client, as it will clear any leftover reserved channels for your priority level.

Example Animations

Some example animations can be found in the animation folder. They can be connected to a twinkle-client process using a pipe.

  • Sets all channels to a random value and quits
  • Set the lightwall to full white (use lightwall.lan as host) and quits
  • Displays a red/green gradient on the lightwall and quits
  • Matrix animation for the lightwall (use lightwall.lan as host)


python2 | ../bin/twinkl-client lightwall.lan 7
python2 lightwall.lan 7
python2 lightwall.lan 7

python2 | ../bin/twinkl-client ampel.lan 7

If you like to use your stdout for other things then piping data to the twinkl client binary you should consider using the twinkl client library.

It offers the following functions:

 * Functions for handling sockets

// Opens a 'connected' upd socket for this host and port. Returns the filedescriptor or -1 on error.
int twinklsocket_open(const char *host, const char *port);

// Sends a twinkl message. Returns 0 on success else -1.
int twinklsocket_send(int sockfd, const struct twinkl_message *message);

// Closes the socket
void twinklsocket_close(int sockfd);

 * Wrappers for handling twinkl messages

// Allocates memory for a twinkl message, returns the pointer
twinkl_message* twinklmsg_create();

// Reset a message to 0 (wrapper for memset)
void twinklmsg_reset(struct twinkl_message *msg);

// Sets the value and marks the channel as 'used' for messages priority level
void twinklmsg_set_value(struct twinkl_message *msg, uint16_t chan, uint8_t value);

// Resets the channel to 0 and unsets the 'used' flag
void twinklmsg_unset_value(struct twinkl_message *msg, uint16_t chan);

// Sets the priority level for the message
void twinklmsg_set_priority(struct twinkl_message *msg, uint8_t priority);

// Free the memory allocated for the message
void twinklmsg_destroy(struct twinkl_message* msg);

To use it from C just include twinklsocket.h and message.h, then link against Keep in mind that there is no need to use the wrapper functions for twinkl messages included in Just directly us the ones in message.h as they can be inlined by your compiler for better performance. Keep in mind that the functions in are named different than the ones in message.h to avoid accidentally using the slower versions.

To use the twinkl client library in other languages than C, the message wrapper function can be used to take of allocating, deallocating and modifing twinkl messages. This is especially usefull for languages without a concept for direct memory management like python. Using the wrapper functions it is only necessary to deal with integers and pointers (which can be represented as integers as well). See animations/ and the example below for details.

twinkl_server = "";
port = "1337";

fd = twinklsocket_open(twinkl_server, port);
if(fd == -1) {

msg = twinklmsg_create();

twinklmsg_set_priority(msg, 0);

twinklmsg_set_value(msg, 23, 42);
twinklmsg_set_value(msg, 46, 5);
// ... more stuff

result = twinklsocket_send(fd, msg);
if(result == -1) {

// Tear down