Devices

A device is anything on a computer’s bus: a terminal, a disk, a card, a sensor, a piston. This section is the programming reference for every one: what it is called, which methods it has, which events it raises, and what its file in /dev does. For how a device is built, crafted or placed, see the Hardware section.

What every device has

Every device has several names, as devices do on a real computer (see Names):

• A slot path, fixed by where it is plugged in: eeprom, sata:0, exp:1. A cabled device has none.
• An id, written id:<uuid>, which every device has however it is connected. The id stays the same if you move a part to another slot.
• A kernel name in mcos, such as redstone0, storage1 or dsp. It is the device’s type followed by a number, counted in bus order. Run lsdev -i to see every device’s name, type, slot path and id.

Every device also has a type, which the bus reports as a lower case word:

Besides its type, a device says a little about itself (board.info, below): its label, and what its kind adds, such as a disk’s tier and capacity. Each page lists these.

How a program reaches a device

There are two ways, and which one you use depends on where your code runs.

In mcos: files in /dev

Programs under mcos never call a device directly. The kernel owns every device and shows every one as a file in /dev. You open a file, read it, write it, or poll it, as on Linux, and its ioctls are the device’s methods by name: sys.ioctl(fd, "push", "front") calls a piston’s push. Each device page has an In mcos section saying what its file does.

lsdev -i
cat /dev/redstone0
echo "north 15" > /dev/redstone0

A device whose data is a table (a redstone card, a sensor) has a driver that turns it into text: a line a face, an event a line. A device with no data says what it is when read (its type, id and methods), and is used through its ioctls. A network card’s data goes through sockets (Networking); its file is its traffic. Terminals are merged into the console (/dev/console).

For everything else mcos offers (processes, sockets, polling), see the sys API.

From the EEPROM: the board API

Code that runs straight from the EEPROM, with no operating system, and the mcos kernel itself, can use a global board. It is the motherboard’s API:

The address is any of the device’s names: its slot path, its id:<uuid>, or console, a virtual device that writes to and reads from every terminal.

A call never stops the machine. If a device is gone, or an argument is wrong, board.invoke returns false and a message such as bad argument #1 (string expected, got nil). This manual writes a method’s results as the values after the leading true, and its failures as the message.

local ok, size = board.invoke("sata:0", "getCapacity")
if ok then
  board.invoke("console", "write", "disk holds " .. size .. " bytes\r\n")
end

Values are Lua’s: strings are bytes (one character a byte), numbers are integers or floats, tables are sequences or maps.

Faces

A device that takes a face takes it as a string. Either a world name (north, south, east, west, up, down), or a name relative to the front of the block the device is in (front, back, left, right, left and right as someone facing the front sees them). A program written with relative names works however the block is turned. Devices answer with world names. See Faces.

Interrupts

A device with news raises an interrupt line, which wakes a computer waiting for it. Interrupts are level-triggered: the line stays up while the device has something waiting, and drops when a program has read it all. The data stays in the device until you take it. See Interrupts.

A device takes data only while a program is running on the computer that holds it. Keys typed at a computer that is off, or a sensor’s events while it is off, are dropped.

Labels

A device on an item can carry a label, which stays on the item. Programs set it with board.setLabel(address, label) or, in mcos, with the label program. A label is at most 32 printable characters. A device with no item to keep it on cannot have one.

Every device