Every device

A device is a block a computer drives: a Traffic Light, a chest, a Create machine, a monitor, a sensor of Create Aeronautics. peripheral.wrap and peripheral.find return an object for it: a table whose fields are the functions of that block, its methods. This page explains what all these objects have in common; the pages of each type (listed below) describe their methods.

local light = peripheral.wrap("left")   -- the Traffic Light on the left face
light.set("green")
print(light.get())                      -- green
print(light.type())                     -- traffic_light

Every computer drives devices, the Tube Computer included: against one of its six faces, or, from the Minicomputer on, anywhere on its Data Cable network. Names, searching and costs are explained in peripheral.

#Calling methods

With a dot, not a colon. The methods of a device are plain functions stored in a table, not methods in the Lua sense: call them with a dot, light.set("green"). With a colon, Brass passes the object itself as the first argument, and the method receives a table where it expected text:

local light = peripheral.wrap("left")
light.set("red")     -- right
light:set("red")     -- wrong: bad argument #1 to 'set' (string expected, got table)

An ordinary table. A device object can be stored in a variable or a table, passed to a function, and looked through with pairs. A short function lists the methods of any device, sorted:

local function methods(device)
  local names = {}
  for name, _ in pairs(device) do
    table.insert(names, name)
  end
  table.sort(names)
  return table.concat(names, " ")
end

for _, name in ipairs(peripheral.list()) do
  print(name .. ": " .. methods(peripheral.wrap(name)))
end

For a Traffic Light, it prints get release set type. The built-in devices program goes further: it shows everything the computer can reach, with live readings.

An object only lives as long as the program: after a reboot, wrap the block again.

#Types

Each device has a type, a short name in English that says what it can do. These are all the types, with the page of their methods:

The types of Create Aeronautics only exist when that mod is installed.

One block, several types. A block can be several things at once. A Create Millstone turns and holds items: it is both kinetic and inventory. A Basin holds items and fluids: inventory and tank. Its object then has the methods of every type together, so one object does it all:

local millstone = peripheral.wrap("left")
print(millstone.speed() .. " RPM")             -- a kinetic method
print(millstone.count() .. " items inside")    -- an inventory method

Its type, though, is a single name: the first of its types, in the order of the table above (the Aeronautics types first, then traffic_light down to tank). The Millstone is kinetic. To find a block by any of its types, use peripheral.list(type) or peripheral.find(type), which look at all of them: peripheral.find("inventory") finds the Millstone too.

local device = peripheral.wrap("left")
if device and device.type() == "inventory" then
  print(device.count() .. " items")
end

#When the block goes away

A device object does not hold the block itself: every method looks for the block again when it is called. So an object never goes stale. Break the chest on the left and put a new one there: the same object reads the new chest.

When the block is gone, or is no longer the right kind, the method stops the program with an error:

A few readings answer nil instead of failing: the get of a Traffic Light that is gone returns nil.

The methods of an object are chosen when it is wrapped. If a different kind of block takes the place (a barrel where the Traffic Light was), the old object keeps the methods of a Traffic Light, which now fail: wrap the block again.

To keep a program alive when a block may disappear, call the method through pcall, which returns a table instead of stopping the program:

local chest = peripheral.wrap("left")
while true do
  local result = pcall(chest.count, "minecraft:coal")
  if result.ok then
    print("coal: " .. result.value)
  else
    print("the coal chest is missing!")
  end
  sleep(5)
end

More on catching errors: pcall and Errors and debugging.