diff --git a/Makefile b/Makefile
index b983b64..6a495cf 100644
--- a/Makefile
+++ b/Makefile
@@ -6,8 +6,8 @@ in: in.c
 out: out.c
 	gcc out.c -Wall -lmonome -o out
 
-test.rom: test.tal
-	uxnasm test.tal test.rom
+basic.rom: examples/basic.tal
+	uxnasm examples/basic.tal basic.rom
 
-test: test.rom
-	./in | uxnemu test.rom | ./out
+test: basic.rom
+	./in /dev/ttyACM0 | uxnemu test.rom | ./out /dev/ttyACM0
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4a6b082
--- /dev/null
+++ b/README.md
@@ -0,0 +1,34 @@
+# uxn-grid
+
+Do monome grid I/O with uxn!
+
+## Building
+
+```
+make
+```
+requires libmonome.
+
+## Usage
+
+use `in` as the uxn input, and `out` as the uxn output:
+```
+./in /dev/ttyACM0 | uxnemu test.rom | ./out /dev/ttyACM0 
+```
+
+`in` outputs grid events as three bytes (state, x, and y). See test.tal for a uxn example of handling this
+
+output messages have the same arguments as they do in [monome OSC](https://monome.org/docs/serialosc/osc). Each argument is given as a byte and the message type is a byte. The message types are:
+
+* 0x00: led/set
+* 0x01: led/all
+* 0x01: led/map
+* 0x03: led/row
+* 0x04: led/col
+* 0x05: led/level/set
+* 0x06: led/level/all
+* 0x07: led/level/map
+* 0x08: led/level/row
+* 0x09: led/level/col
+
+so to send a `led/set 1 2 1` message, send the bytes `0x00 0x01 0x02 0x01` to the out program (if you are using this in a pipe with uxn, this is `.Console/write`)
\ No newline at end of file
diff --git a/test.tal b/examples/basic.tal
similarity index 85%
rename from test.tal
rename to examples/basic.tal
index a76b2fa..5364443 100644
--- a/test.tal
+++ b/examples/basic.tal
@@ -1,8 +1,5 @@
-( a blank file )
 
 %RTN { JMP2r }
-%DEBUG  { ;print-hex JSR2 #0a .Console/write DEO }
-%DEBUG2 { SWP ;print-hex JSR2 ;print-hex JSR2 #0a .Console/write DEO }
 
 ( devices )
 
@@ -67,22 +64,13 @@ BRK
 
 ;&message LDA .Screen/sprite DEO ( draw the sprite )
 
-( output to the grid to change the square )
-;&message LDA .Console/write DEO
+( output to the grid to change the square. Write a #00 to send a set message, then the x, y, and state )
+#00 .Console/write DEO
 ;&message #0001 ADD2 LDA .Console/write DEO
 ;&message #0002 ADD2 LDA .Console/write DEO
+;&message LDA .Console/write DEO
 
 BRK
 
-@print-hex ( value -- )
-	
-	STHk #04 SFT ,&parse JSR .Console/write DEO
-	STHr #0f AND ,&parse JSR .Console/write DEO
-	RTN
-	&parse ( value -- char )
-		DUP #09 GTH ,&above JCN #30 ADD RTN &above #09 SUB #60 ADD RTN
-
-RTN
-
 @block [ ffff ffff ffff ffff ]
 
diff --git a/in.c b/in.c
index 5bf874e..0bcf283 100644
--- a/in.c
+++ b/in.c
@@ -2,8 +2,6 @@
 #include <stdio.h>
 #include <monome.h>
 
-#define MONOME_DEVICE "/dev/ttyACM0"
-
 void handle_press(const monome_event_t *e, void *data) {
 	unsigned int x, y;
 
@@ -27,10 +25,13 @@ void handle_release(const monome_event_t *e, void *data) {
 }
 
 int main(int argc, char *argv[]) {
+	if(argc != 2) {
+		fprintf(stderr, "Please provide a serial port.\n");
+	}
 	setbuf(stdout, NULL);
 	monome_t *monome;
 
-	if( !(monome = monome_open(MONOME_DEVICE, "8000")) )
+	if( !(monome = monome_open(argv[1], "8000")) )
 		return -1;
 
 	monome_led_all(monome, 0);
diff --git a/out.c b/out.c
index be51a1b..bf88017 100644
--- a/out.c
+++ b/out.c
@@ -2,8 +2,6 @@
 #include <monome.h>
 #include <string.h>
 
-#define MONOME_DEVICE "/dev/ttyACM0"
-
 /* all the message types that the grid supports. The enum values are also the bytes */
 enum messages { SET = 0, ALL, MAP, ROW, COL, LEVEL_SET, LEVEL_ALL, LEVEL_MAP, LEVEL_ROW, LEVEL_COL };
 /* lengths of all the messages, corresponding to their enum values */
@@ -15,13 +13,17 @@ int msg[68];
 int c;
 
 int main(int argc, char *argv[]) {
+	if(argc != 2) {
+		fprintf(stderr, "Please provide a serial port.\n");
+	}
+	
 	/* make stdin unbuffered */
 	setbuf(stdin, NULL);
 	
 	/* connect to monome */
 	monome_t *monome;
 	
-	if( !(monome = monome_open(MONOME_DEVICE, "8000")) )
+	if( !(monome = monome_open(argv[1], "8000")) )
 		return -1;
 	/* in a loop (to recieve every character) */
 	for(;;) {