2015-09-17 01:37:37 +02:00
|
|
|
twinkl-client
|
|
|
|
=============
|
|
|
|
|
|
|
|
Compile
|
|
|
|
-------
|
|
|
|
```
|
|
|
|
git clone git@github.com:LongHairedHacker/twinkl-client.git
|
|
|
|
cd twinkl-client
|
|
|
|
git submodule init
|
|
|
|
git submodule update
|
|
|
|
make
|
|
|
|
```
|
|
|
|
|
|
|
|
Usage
|
|
|
|
-----
|
|
|
|
```
|
|
|
|
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.
|
2015-09-17 02:27:11 +02:00
|
|
|
|
|
|
|
|
|
|
|
Example Animations
|
|
|
|
------------------
|
|
|
|
Some example animations can be found in the animation folder.
|
|
|
|
They can be connected to a twinkle-client process using a pipe.
|
|
|
|
|
|
|
|
* `randomvalues.py` Sets all channels to a random value and quits
|
|
|
|
* `fullwhite.py` Set the lightwall to full white (use *lightwall.lan* as host) and quits
|
|
|
|
* `gradient.py` Displays a red/green gradient on the lightwall and quits
|
|
|
|
* `matrix.py` Matrix animation for the lightwall (use *lightwall.lan* as host)
|
|
|
|
|
|
|
|
**Examples:**
|
|
|
|
|
|
|
|
```
|
|
|
|
python2 gradient.py | ../bin/twinkl-client lightwall.lan 7
|
2015-10-20 21:23:06 +02:00
|
|
|
python2 fullwithe.py lightwall.lan 7
|
|
|
|
python2 matrix.py lightwall.lan 7
|
2015-09-17 02:27:11 +02:00
|
|
|
|
|
|
|
python2 random.py | ../bin/twinkl-client ampel.lan 7
|
|
|
|
```
|
2015-10-20 20:37:27 +02:00
|
|
|
|
|
|
|
twinklclient.so
|
|
|
|
===============
|
|
|
|
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:
|
|
|
|
```C
|
|
|
|
/*
|
|
|
|
* Functions for handling sockets
|
|
|
|
*/
|
|
|
|
|
2015-10-20 21:23:06 +02:00
|
|
|
// Opens a 'connected' upd socket for this host and port. Returns the filedescriptor or -1 on error.
|
2015-10-20 20:37:27 +02:00
|
|
|
int twinklsocket_open(const char *host, const char *port);
|
|
|
|
|
2015-10-20 21:23:06 +02:00
|
|
|
// Sends a twinkl message. Returns 0 on success else -1.
|
|
|
|
int twinklsocket_send(int sockfd, const struct twinkl_message *message);
|
2015-10-20 20:37:27 +02:00
|
|
|
|
|
|
|
// 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 `twinklclient.so`.
|
|
|
|
Keep in mind that there is no need to use the wrapper functions for twinkl
|
|
|
|
messages included in `twinklclient.so`.
|
|
|
|
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 `twinklclient.so` 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/twinklclient.py` and the example below for details.
|
|
|
|
|
|
|
|
```C
|
2015-10-20 21:23:06 +02:00
|
|
|
twinkl_server = "127.0.0.1";
|
2015-10-20 20:37:27 +02:00
|
|
|
port = "1337";
|
|
|
|
|
2015-10-20 21:23:06 +02:00
|
|
|
fd = twinklsocket_open(twinkl_server, port);
|
|
|
|
if(fd == -1) {
|
|
|
|
PANIC();
|
|
|
|
}
|
2015-10-20 20:37:27 +02:00
|
|
|
|
2015-10-20 21:23:06 +02:00
|
|
|
msg = twinklmsg_create();
|
2015-10-20 20:37:27 +02:00
|
|
|
|
|
|
|
twinklmsg_set_priority(msg, 0);
|
|
|
|
|
|
|
|
twinklmsg_set_value(msg, 23, 42);
|
|
|
|
twinklmsg_set_value(msg, 46, 5);
|
|
|
|
// ... more stuff
|
|
|
|
|
2015-10-20 21:23:06 +02:00
|
|
|
result = twinklsocket_send(fd, msg);
|
|
|
|
if(result == -1) {
|
|
|
|
PANIC();
|
|
|
|
}
|
2015-10-20 20:37:27 +02:00
|
|
|
|
|
|
|
// Tear down
|
|
|
|
|
|
|
|
twinklsocket_close(fd);
|
|
|
|
|
|
|
|
twinklmsg_destroy(msg);
|
|
|
|
```
|