net

The address of this computer, the number other computers use to send it a message. It is the same as os.id().

print("My address: " .. net.id())

Write it on a sign next to the computer, or give the computer a name with the shell command label (or os.label): net.computers shows the names of the computers in reach, so a program can find "the warehouse" without knowing its number.

See also net.computers()

Sends data to the computer whose address is id.

local FACTORY = 12
local ok = net.send(FACTORY, {type = "order", item = "minecraft:iron_ingot", count = 64}, "orders")
if not ok then
  print("The factory does not answer: out of reach, switched off or overloaded.")
end

net.send returns false when no computer with that address is in reach (it is too far, in an unloaded chunk, in another dimension, or it is this very computer), when it is switched off, or when its receive buffer is full. It does not wait: the program goes on at once.

The data can be left out, for a message whose channel says everything:

net.send(12, nil, "ping")

Wrong arguments stop the program: bad argument #1 to 'send' (number expected, got string) when the address is not a number, bad argument #3 to 'send' (string expected, got number) when the channel is not a string.

Besides its 32 instructions, a send costs one instruction for each value of the message and one for every 16 characters (the copy), plus the search for the receiver: one instruction per block space around the computer's Data Cables and, on a Personal Computer, a Microcontroller or a Modern Computer, one per computer loaded in the world. On a large network, send a few big messages rather than many small ones.

See also net.broadcast() net.receive()

Sends data to every computer in reach, and returns how many accepted it.

A broadcast suits news that anyone may want: a sensor reading, an alarm, "I am here". The computers that do not care simply ignore the channel.

local count = net.broadcast("creeper at the north gate!", "alarm")
print("Warned " .. count .. " computers")

A computer that is off, out of reach or overloaded is skipped: it is not counted, and there is no error. 0 means nobody heard you. A broadcast costs 64 instructions, plus the copy and the search like net.send, plus 8 per computer in reach.

See also net.send()

Waits for the next message and returns it. With a timeout, gives up after that many seconds and returns nil.

print("Listening as #" .. net.id())
while true do
  local m = net.receive()
  print("#" .. m.sender .. " on " .. m.channel .. ": " .. tostring(m.data))
end

The fields of a message, written here by hand to show what a program receives:

local m = {name = "message", sender = 7, channel = "stock", via = "wifi", distance = 182.4,
  data = {item = "minecraft:iron_ingot", count = 1830}}
print("from #" .. m.sender .. " by " .. m.via .. ", " .. m.distance .. " blocks away")
print(m.data.item .. ": " .. m.data.count)

from #7 by wifi, 182.4 blocks away
minecraft:iron_ingot: 1830

The timeout is rounded up to the next tick (a twentieth of a second), and is at least one tick: net.receive(0) returns a message already waiting, or nil one tick later. Use a timeout whenever an answer may never come, so that the program does not hang:

net.send(12, nil, "ping")
local m = net.receive(2)
if m == nil then
  print("No answer within 2 seconds")
end

The same messages come out of os.pull_event, which is the way to wait for messages and something else. os.pull_event("message") does exactly what net.receive() does. A warehouse computer that reports its stock every 10 seconds and answers questions at any moment:

local vault = peripheral.wrap("back")
local timer = os.start_timer(10)
while true do
  local e = os.pull_event()
  if e.name == "message" and e.channel == "stock" and e.data == "how much?" then
    net.send(e.sender, vault.count("minecraft:iron_ingot"), "stock")
  elseif e.name == "timer" and e.id == timer then
    net.broadcast(vault.count("minecraft:iron_ingot"), "stock")
    timer = os.start_timer(10)
  end
end

Filter what you accept. Any computer in reach can send on any channel, so check the channel, the sender and the shape of the data before acting. A door that only obeys the two control rooms:

local TRUSTED = {[4] = true, [9] = true}
local function accept(m)
  return m.channel == "door" and TRUSTED[m.sender] == true
end
print(accept({sender = 4, channel = "door", data = "open"}))
print(accept({sender = 5, channel = "door", data = "open"}))
print(accept({sender = 9, channel = "chat", data = "hi"}))

true
false
false

In the real program, accept sits in the receive loop: if accept(m) then rs.set("top", m.data == "open") end. m.via == "cable" is another useful test: only a computer wired to yours can pass it.

See also net.send() os.pull_event() Events

The computers this one can send to right now, each one as a table:

The computers on the same cable come first. A computer that is switched off is listed (it is in reach), but net.send to it returns false.

for _, c in ipairs(net.computers()) do
  print("#" .. c.id, c.via, c.distance .. " blocks", c.label or "")
end

Find a computer by its label instead of writing its address in the program, so that it keeps working when you replace a computer:

local function find(label)
  for _, c in ipairs(net.computers()) do
    if c.label == label then return c.id end
  end
  return nil
end

local warehouse = find("warehouse")
if warehouse then
  net.send(warehouse, "how much?", "stock")
end

net.computers costs 64 instructions plus the search (see net.send): call it once at start, not in every turn of a loop.

See also net.send() net.networks()

The Wi-Fi networks this computer is on: those of its own Wi-Fi Routers, and those of the routers its radios reach. Each one is a table:

for _, n in ipairs(net.networks()) do
  local kind = "nearby"
  if n.own then kind = "mine" end
  print(n.ssid .. ": " .. n.routers .. " routers, nearest " .. n.distance .. " blocks (" .. kind .. ")")
end

The list is empty on a Minicomputer, without any router in reach, and with routers that have no SSID yet: a router gets its network name from a program, with radio.set_ssid().

See also net.computers() radio.set_ssid()

Tells whether the computer has a radio: a Radio Modem or a Wi-Fi Router touching it, or anywhere on its Data Cable network. Always false on a Minicomputer, which only uses cables.

if not net.wireless() then
  print("No radio: only computers on the cable will hear me.")
end

#Common patterns

A chat. Each line you type goes to every computer in reach; the messages received meanwhile are shown after each line (press Enter on an empty line to look for new ones). The messages are tables with the author's name, so that the others know who speaks:

local me = os.label() or ("#" .. net.id())
print("Chat as " .. me .. ". Type /quit to leave.")
while true do
  write("> ")
  local line = read()
  if line == "/quit" then break end
  if line ~= "" then
    local heard = net.broadcast({from = me, text = line}, "chat")
    print("(" .. heard .. " listening)")
  end
  local m = net.receive(0)
  while m do
    if m.channel == "chat" and type(m.data) == "table" then
      print(tostring(m.data.from) .. ": " .. tostring(m.data.text))
    end
    m = net.receive(0)
  end
end

Messages that arrive while read() waits for your line are kept in the queue, so none is lost.

A question with a timeout and retries. A message can be lost: the other computer was off, overloaded, or its chunk was not loaded. A client that asks the factory for its speed tries three times, and recognises the answer by an id it puts in the question:

local FACTORY = 12
local next_id = 1

local function ask(question)
  local id = next_id
  next_id = next_id + 1
  for attempt = 1, 3 do
    net.send(FACTORY, {type = "request", id = id, question = question}, "factory")
    local deadline = os.clock() + 2
    while os.clock() < deadline do
      local m = net.receive(deadline - os.clock())
      if m and m.sender == FACTORY and type(m.data) == "table"
          and m.data.type == "reply" and m.data.id == id then
        return m.data.answer
      end
    end
  end
  return nil
end

local rpm = ask("speed")
if rpm == nil then print("The factory does not answer") else print("Factory at " .. rpm .. " RPM") end

The factory side answers each request with the same id:

local motor = peripheral.wrap("top")   -- a Rotation Speed Controller
while true do
  local m = net.receive()
  local d = m.data
  if m.channel == "factory" and type(d) == "table" and d.type == "request" then
    local answer = nil
    if d.question == "speed" then answer = motor.speed() end
    net.send(m.sender, {type = "reply", id = d.id, answer = answer}, "factory")
  end
end

A retry may reach the factory twice (when only the answer was lost), so keep requests safe to repeat: "set the speed to 64" rather than "add 16 RPM".

Sensors and a dashboard. Each sensor broadcasts its reading every few seconds on the "sensors" channel; the dashboard keeps the last reading of each one and redraws every second, which also shows how old each value is:

-- on each sensor (a Microcontroller next to a vault)
local vault = peripheral.wrap("back")
while true do
  net.broadcast({what = "iron", value = vault.count("minecraft:iron_ingot")}, "sensors")
  sleep(5)
end

-- on the dashboard
local readings = {}
while true do
  local m = net.receive(1)   -- nil after one second: time to redraw anyway
  if m and m.channel == "sensors" and type(m.data) == "table" then
    readings[m.sender] = {what = m.data.what, value = m.data.value, at = os.clock()}
  end
  term.clear()
  term.set_cursor(1, 1)
  for id, r in pairs(readings) do
    local age = math.floor(os.clock() - r.at)
    print("#" .. id .. " " .. tostring(r.what) .. ": " .. tostring(r.value) .. " (" .. age .. " s ago)")
  end
end

A sensor whose age keeps growing has stopped talking: broken, switched off, or its chunk unloaded. A complete three-computer version of this, with commands and acknowledgements, is in Networks. The built-in programs talk, listen and pong are other complete examples.

See also net.networks()