Serial

serial( channel, address, [length] )
Sends or receives data from a serial "channel."
channel

The channel ID.

address

The memory address to read from / write to.

length

The number of bytes to read / write. Use 1/8th values to send partial bit strings. The default length is 1.

`serial()` can read or write streams of data from and to various "channels" that interact with the host environment. Channels can:

* Communicate a precisely timed sequence of bits via GPIO pins (Raspberry Pi) or a JavaScript array (web player)
* Pause using precise timing (microseconds), such as to tune GPIO serial communication
* Read from and write to the host operating system's input and output streams
* Read from and write to a file named on the PICO-8 command line
* Read a file dragged into the PICO-8 window by the user
* Read an image file dragged into the PICO-8 window by the user, converted automatically to PICO-8's image format and color palette
* (Undocumented:) Play a digital PCM audio sample at 5 KHz

Process stream and file I/O are limited to the PICO-8 development environment and do not work in exported carts or the BBS.

Drag-and-drop *is* supported in exported carts, limited to files of size 256 Kb or images of pixel size 128x128.

## Reading and writing

To read from a serial channel, call `serial()` in an expression context. The return value is the number of bytes read. The data read from the channel is written to memory starting at the specified address, up to address + size.

```
size = serial(0x804, 0x4300, 0x1000)

```

To read an arbitrary amount of data until all data is exhausted, call `serial()` repeatedly until it returns a size of 0.

```
repeat
 size = serial(0x804, 0x4300, 0x1000)
 for i=0,size do
  b = peek(0x4300 + i)
  -- ...process byte b...
 end
until(size == 0)

```

To write to a serial channel, call `serial()` in a statement context, i.e. not assigned to a variable or used in an expression.

```
poke(0x4300, 72)
poke(0x4301, 73)
serial(0x805, 0x4300, 2)

```

## GPIO serial communication

Channels 0x000 through 0x0fe correspond to Raspberry Pi GPIO pins. Values 0x00 and 0xff are off and on, respectively.

GPIO pin values are also available to the browser JavaScript environment of the web player, in a global named `pico8_gpio` that you declare with: `var pico8_gpio = Array(128);`

Channel 0x0ff is a delay register. Pass the duration of the delay as the "length" parameter, as a number of microseconds.

Channels 0x400 and 0x401 are specifically for a WS281X addressable LED light string.

## Drag-and-drop files

A PICO-8 cart can accept files dragged into the PICO-8 window by the user. If the file is an image file, PICO-8 attempts to convert the image to the PICO-8 color palette and present it to the cart as PICO-8 image data.

When the user drops a non-image file, `stat(120)` returns `true`, and the data can be read from channel 0x800.

When the user drops an image file, `stat(121)` returns `true`, and the converted image data can be read from channel 0x802. The first 4 bytes are the image's width and height (2 bytes each little-endian, like `peek2()`), followed by the image in reading order, one byte per pixel, color-fitted to the display palette at the time the file was dropped.

The maximum transfer rate for drag-and-dropped files is 64 Kb/second. The `serial()` command blocks the CPU until completed. Note that the `stat()` call will not block, so you can detect when a file is ready, do something else, then call `serial()` to read the file when appropriate.

## Host OS streams and files

The host OS in which PICO-8 runs can pass data to the process using the "standard input" stream, and receive data from the process using the "standard output" stream. A cart can access these streams for the PICO-8 process using channel 0x804 for STDIN (readable) and 0x805 for STDOUT (writable). This typically requires invoking PICO-8 from the command line.

For example, to run the cart `mycart.p8` and pour the contents of the file `myfile.txt` into STDIN, invoke PICO-8 from the command line this way:

```
pico8 < myfile.txt -run mycart.p8

```

PICO-8 can also accept the name of a file as a command line argument to be either an input file or an output file, independent of the standard I/O streams. To read an input file, use the `-i filename` command line argument when invoking PICO-8, then read it from channel 0x806. To write to an output file, use the `-o filename` command line arugment, then write to it from channel 0x807.

```
pico8 -i myfile.txt -run mycart.p8

```

The maximum transfer rate for streams and files is 64 Kb/second. The `serial()` command blocks the CPU until completed.

## Play PCM audio samples

You can play a 5 KHz (5512.5 Hz, specifically) PCM digital audio sample by writing the audio data to channel 0x808. The playback buffer can hold up to 2048 bytes.

`stat(108)` and `stat(109)` return information about the audio playback.

## Examples

### APA102 LED string

To send a byte one bit at a time to a typical APA102 LED string:

```
val = 42          -- value to send
dat = 16 clk = 15 -- data and clock pins depend on device
poke(0x4300,0)    -- data to send (single bytes: 0 or 0xff)
poke(0x4301,0xff)
for b=0,7 do
  -- send the bit (high first)
  serial(dat, band(val, shl(1,7-b))>0 and 0x4301 or 0x4300, 1)
  -- cycle the clock
  serial(clk, 0x4301)
  serial(0xff, 5) -- delay 5
  serial(clk, 0x4300)
  serial(0xff, 5) -- delay 5
end

```

### Reading a file from stdin

To read a file from the host operating system's standard input stream in blocks of 4,096 (0x1000) bytes, and print it to the screen one character at a time:

```
cls()
repeat
 size = serial(0x804,0x4300,0x1000)
 for i=0,size do
  print(chr(peek(0x4300+i)).."\0")
 end
until(size == 0)

```

Run this example from the host operating system's command line:

```
pico8 < myfile.txt -run mycart.p8

```

## See Also

* GPIO
* `export`
* `stat()`