506 lines
18 KiB
Lua
506 lines
18 KiB
Lua
-- SPDX-FileCopyrightText: 2017 Daniel Ratcliffe
|
|
--
|
|
-- SPDX-License-Identifier: LicenseRef-CCPL
|
|
|
|
--[[- Communicate with other computers by using [modems][`modem`]. [`rednet`]
|
|
provides a layer of abstraction on top of the main [`modem`] peripheral, making
|
|
it slightly easier to use.
|
|
|
|
## Basic usage
|
|
In order to send a message between two computers, each computer must have a
|
|
modem on one of its sides (or in the case of pocket computers and turtles, the
|
|
modem must be equipped as an upgrade). The two computers should then call
|
|
[`rednet.open`], which sets up the modems ready to send and receive messages.
|
|
|
|
Once rednet is opened, you can send messages using [`rednet.send`] and receive
|
|
them using [`rednet.receive`]. It's also possible to send a message to _every_
|
|
rednet-using computer using [`rednet.broadcast`].
|
|
|
|
> [Network security][!WARNING]
|
|
>
|
|
> While rednet provides a friendly way to send messages to specific computers, it
|
|
> doesn't provide any guarantees about security. Other computers could be
|
|
> listening in to your messages, or even pretending to send messages from other computers!
|
|
>
|
|
> If you're playing on a multi-player server (or at least one where you don't
|
|
> trust other players), it's worth encrypting or signing your rednet messages.
|
|
|
|
## Protocols and hostnames
|
|
Several rednet messages accept "protocol"s - simple string names describing what
|
|
a message is about. When sending messages using [`rednet.send`] and
|
|
[`rednet.broadcast`], you can optionally specify a protocol for the message. This
|
|
same protocol can then be given to [`rednet.receive`], to ignore all messages not
|
|
using this protocol.
|
|
|
|
It's also possible to look-up computers based on protocols, providing a basic
|
|
system for service discovery and [DNS]. A computer can advertise that it
|
|
supports a particular protocol with [`rednet.host`], also providing a friendly
|
|
"hostname". Other computers may then find all computers which support this
|
|
protocol using [`rednet.lookup`].
|
|
|
|
[DNS]: https://en.wikipedia.org/wiki/Domain_Name_System "Domain Name System"
|
|
|
|
@module rednet
|
|
@since 1.2
|
|
@see rednet_message Queued when a rednet message is received.
|
|
@see modem Rednet is built on top of the modem peripheral. Modems provide a more
|
|
bare-bones but flexible interface.
|
|
]]
|
|
|
|
local expect = dofile("rom/modules/main/cc/expect.lua").expect
|
|
|
|
--- The channel used by the Rednet API to [`broadcast`] messages.
|
|
CHANNEL_BROADCAST = 65535
|
|
|
|
--- The channel used by the Rednet API to repeat messages.
|
|
CHANNEL_REPEAT = 65533
|
|
|
|
--- The number of channels rednet reserves for computer IDs. Computers with IDs
|
|
-- greater or equal to this limit wrap around to 0.
|
|
MAX_ID_CHANNELS = 65500
|
|
|
|
local received_messages = {}
|
|
local hostnames = {}
|
|
local prune_received_timer
|
|
|
|
local function id_as_channel(id)
|
|
return (id or os.getComputerID()) % MAX_ID_CHANNELS
|
|
end
|
|
|
|
--[[- Opens a modem with the given [`peripheral`] name, allowing it to send and
|
|
receive messages over rednet.
|
|
|
|
This will open the modem on two channels: one which has the same
|
|
[ID][`os.getComputerID`] as the computer, and another on
|
|
[the broadcast channel][`CHANNEL_BROADCAST`].
|
|
|
|
@tparam string modem The name of the modem to open.
|
|
@throws If there is no such modem with the given name
|
|
@usage Open rednet on the back of the computer, allowing you to send and receive
|
|
rednet messages using it.
|
|
|
|
rednet.open("back")
|
|
|
|
@usage Open rednet on all attached modems. This abuses the "filter" argument to
|
|
[`peripheral.find`].
|
|
|
|
peripheral.find("modem", rednet.open)
|
|
@see rednet.close
|
|
@see rednet.isOpen
|
|
]]
|
|
function open(modem)
|
|
expect(1, modem, "string")
|
|
if peripheral.getType(modem) ~= "modem" then
|
|
error("No such modem: " .. modem, 2)
|
|
end
|
|
peripheral.call(modem, "open", id_as_channel())
|
|
peripheral.call(modem, "open", CHANNEL_BROADCAST)
|
|
end
|
|
|
|
--- Close a modem with the given [`peripheral`] name, meaning it can no longer
|
|
-- send and receive rednet messages.
|
|
--
|
|
-- @tparam[opt] string modem The side the modem exists on. If not given, all
|
|
-- open modems will be closed.
|
|
-- @throws If there is no such modem with the given name
|
|
-- @see rednet.open
|
|
function close(modem)
|
|
expect(1, modem, "string", "nil")
|
|
if modem then
|
|
-- Close a specific modem
|
|
if peripheral.getType(modem) ~= "modem" then
|
|
error("No such modem: " .. modem, 2)
|
|
end
|
|
peripheral.call(modem, "close", id_as_channel())
|
|
peripheral.call(modem, "close", CHANNEL_BROADCAST)
|
|
else
|
|
-- Close all modems
|
|
for _, modem in ipairs(peripheral.getNames()) do
|
|
if isOpen(modem) then
|
|
close(modem)
|
|
end
|
|
end
|
|
end
|
|
end
|
|
|
|
--- Determine if rednet is currently open.
|
|
--
|
|
-- @tparam[opt] string modem Which modem to check. If not given, all connected
|
|
-- modems will be checked.
|
|
-- @treturn boolean If the given modem is open.
|
|
-- @since 1.31
|
|
-- @see rednet.open
|
|
function isOpen(modem)
|
|
expect(1, modem, "string", "nil")
|
|
if modem then
|
|
-- Check if a specific modem is open
|
|
if peripheral.getType(modem) == "modem" then
|
|
return peripheral.call(modem, "isOpen", id_as_channel()) and peripheral.call(modem, "isOpen", CHANNEL_BROADCAST)
|
|
end
|
|
else
|
|
-- Check if any modem is open
|
|
for _, modem in ipairs(peripheral.getNames()) do
|
|
if isOpen(modem) then
|
|
return true
|
|
end
|
|
end
|
|
end
|
|
return false
|
|
end
|
|
|
|
--[[- Allows a computer or turtle with an attached modem to send a message
|
|
intended for a computer with a specific ID. At least one such modem must first
|
|
be [opened][`rednet.open`] before sending is possible.
|
|
|
|
Assuming the target was in range and also had a correctly opened modem, the
|
|
target computer may then use [`rednet.receive`] to collect the message.
|
|
|
|
@tparam number recipient The ID of the receiving computer.
|
|
@param message The message to send. Like with [`modem.transmit`], this can
|
|
contain any primitive type (numbers, booleans and strings) as well as
|
|
tables. Other types (like functions), as well as metatables, will not be
|
|
transmitted.
|
|
@tparam[opt] string protocol The "protocol" to send this message under. When
|
|
using [`rednet.receive`] one can filter to only receive messages sent under a
|
|
particular protocol.
|
|
@treturn boolean If this message was successfully sent (i.e. if rednet is
|
|
currently [open][`rednet.open`]). Note, this does not guarantee the message was
|
|
actually _received_.
|
|
@changed 1.6 Added protocol parameter.
|
|
@changed 1.82.0 Now returns whether the message was successfully sent.
|
|
@see rednet.receive
|
|
@usage Send a message to computer #2.
|
|
|
|
rednet.send(2, "Hello from rednet!")
|
|
]]
|
|
function send(recipient, message, protocol)
|
|
expect(1, recipient, "number")
|
|
expect(3, protocol, "string", "nil")
|
|
-- Generate a (probably) unique message ID
|
|
-- We could do other things to guarantee uniqueness, but we really don't need to
|
|
-- Store it to ensure we don't get our own messages back
|
|
local message_id = math.random(1, 2147483647)
|
|
received_messages[message_id] = os.clock() + 9.5
|
|
if not prune_received_timer then prune_received_timer = os.startTimer(10) end
|
|
|
|
-- Create the message
|
|
local reply_channel = id_as_channel()
|
|
local message_wrapper = {
|
|
nMessageID = message_id,
|
|
nRecipient = recipient,
|
|
nSender = os.getComputerID(),
|
|
message = message,
|
|
sProtocol = protocol,
|
|
}
|
|
|
|
local sent = false
|
|
if recipient == os.getComputerID() then
|
|
-- Loopback to ourselves
|
|
os.queueEvent("rednet_message", os.getComputerID(), message, protocol)
|
|
sent = true
|
|
else
|
|
-- Send on all open modems, to the target and to repeaters
|
|
if recipient ~= CHANNEL_BROADCAST then
|
|
recipient = id_as_channel(recipient)
|
|
end
|
|
|
|
for _, modem in ipairs(peripheral.getNames()) do
|
|
if isOpen(modem) then
|
|
peripheral.call(modem, "transmit", recipient, reply_channel, message_wrapper)
|
|
peripheral.call(modem, "transmit", CHANNEL_REPEAT, reply_channel, message_wrapper)
|
|
sent = true
|
|
end
|
|
end
|
|
end
|
|
|
|
return sent
|
|
end
|
|
|
|
--[[- Broadcasts a string message over the predefined [`CHANNEL_BROADCAST`]
|
|
channel. The message will be received by every device listening to rednet.
|
|
|
|
@param message The message to send. This should not contain coroutines or
|
|
functions, as they will be converted to [`nil`].
|
|
@tparam[opt] string protocol The "protocol" to send this message under. When
|
|
using [`rednet.receive`] one can filter to only receive messages sent under a
|
|
particular protocol.
|
|
@see rednet.receive
|
|
@changed 1.6 Added protocol parameter.
|
|
@usage Broadcast the words "Hello, world!" to every computer using rednet.
|
|
|
|
rednet.broadcast("Hello, world!")
|
|
]]
|
|
function broadcast(message, protocol)
|
|
expect(2, protocol, "string", "nil")
|
|
send(CHANNEL_BROADCAST, message, protocol)
|
|
end
|
|
|
|
--[[- Wait for a rednet message to be received, or until `nTimeout` seconds have
|
|
elapsed.
|
|
|
|
@tparam[opt] string protocol_filter The protocol the received message must be
|
|
sent with. If specified, any messages not sent under this protocol will be
|
|
discarded.
|
|
@tparam[opt] number timeout The number of seconds to wait if no message is
|
|
received.
|
|
@treturn[1] number The computer which sent this message
|
|
@return[1] The received message
|
|
@treturn[1] string|nil The protocol this message was sent under.
|
|
@treturn[2] nil If the timeout elapsed and no message was received.
|
|
@see rednet.broadcast
|
|
@see rednet.send
|
|
@changed 1.6 Added protocol filter parameter.
|
|
@usage Receive a rednet message.
|
|
|
|
local id, message = rednet.receive()
|
|
print(("Computer %d sent message %s"):format(id, message))
|
|
|
|
@usage Receive a message, stopping after 5 seconds if no message was received.
|
|
|
|
local id, message = rednet.receive(nil, 5)
|
|
if not id then
|
|
printError("No message received")
|
|
else
|
|
print(("Computer %d sent message %s"):format(id, message))
|
|
end
|
|
|
|
@usage Receive a message from computer #2.
|
|
|
|
local id, message
|
|
repeat
|
|
id, message = rednet.receive()
|
|
until id == 2
|
|
|
|
print(message)
|
|
]]
|
|
function receive(protocol_filter, timeout)
|
|
-- The parameters used to be ( nTimeout ), detect this case for backwards compatibility
|
|
if type(protocol_filter) == "number" and timeout == nil then
|
|
protocol_filter, timeout = nil, protocol_filter
|
|
end
|
|
expect(1, protocol_filter, "string", "nil")
|
|
expect(2, timeout, "number", "nil")
|
|
|
|
-- Start the timer
|
|
local timer = nil
|
|
local event_filter = nil
|
|
if timeout then
|
|
timer = os.startTimer(timeout)
|
|
event_filter = nil
|
|
else
|
|
event_filter = "rednet_message"
|
|
end
|
|
|
|
-- Wait for events
|
|
while true do
|
|
local event, p1, p2, p3 = os.pullEvent(event_filter)
|
|
if event == "rednet_message" then
|
|
-- Return the first matching rednet_message
|
|
local sender_id, message, protocol = p1, p2, p3
|
|
if protocol_filter == nil or protocol == protocol_filter then
|
|
return sender_id, message, protocol
|
|
end
|
|
elseif event == "timer" then
|
|
-- Return nil if we timeout
|
|
if p1 == timer then
|
|
return nil
|
|
end
|
|
end
|
|
end
|
|
end
|
|
|
|
--[[- Register the system as "hosting" the desired protocol under the specified
|
|
name. If a rednet [lookup][`rednet.lookup`] is performed for that protocol (and
|
|
maybe name) on the same network, the registered system will automatically
|
|
respond via a background process, hence providing the system performing the
|
|
lookup with its ID number.
|
|
|
|
Multiple computers may not register themselves on the same network as having the
|
|
same names against the same protocols, and the title `localhost` is specifically
|
|
reserved. They may, however, share names as long as their hosted protocols are
|
|
different, or if they only join a given network after "registering" themselves
|
|
before doing so (eg while offline or part of a different network).
|
|
|
|
@tparam string protocol The protocol this computer provides.
|
|
@tparam string hostname The name this computer exposes for the given protocol.
|
|
@throws If trying to register a hostname which is reserved, or currently in use.
|
|
@see rednet.unhost
|
|
@see rednet.lookup
|
|
@since 1.6
|
|
]]
|
|
function host(protocol, hostname)
|
|
expect(1, protocol, "string")
|
|
expect(2, hostname, "string")
|
|
if hostname == "localhost" then
|
|
error("Reserved hostname", 2)
|
|
end
|
|
if hostnames[protocol] ~= hostname then
|
|
if lookup(protocol, hostname) ~= nil then
|
|
error("Hostname in use", 2)
|
|
end
|
|
hostnames[protocol] = hostname
|
|
end
|
|
end
|
|
|
|
--- Stop [hosting][`rednet.host`] a specific protocol, meaning it will no longer
|
|
-- respond to [`rednet.lookup`] requests.
|
|
--
|
|
-- @tparam string protocol The protocol to unregister your self from.
|
|
-- @since 1.6
|
|
function unhost(protocol)
|
|
expect(1, protocol, "string")
|
|
hostnames[protocol] = nil
|
|
end
|
|
|
|
--[[- Search the local rednet network for systems [hosting][`rednet.host`] the
|
|
desired protocol and returns any computer IDs that respond as "registered"
|
|
against it.
|
|
|
|
If a hostname is specified, only one ID will be returned (assuming an exact
|
|
match is found).
|
|
|
|
@tparam string protocol The protocol to search for.
|
|
@tparam[opt] string hostname The hostname to search for.
|
|
|
|
@treturn[1] number... A list of computer IDs hosting the given protocol.
|
|
@treturn[2] number|nil The computer ID with the provided hostname and protocol,
|
|
or [`nil`] if none exists.
|
|
@since 1.6
|
|
@usage Find all computers which are hosting the `"chat"` protocol.
|
|
|
|
local computers = {rednet.lookup("chat")}
|
|
print(#computers .. " computers available to chat")
|
|
for _, computer in pairs(computers) do
|
|
print("Computer #" .. computer)
|
|
end
|
|
|
|
@usage Find a computer hosting the `"chat"` protocol with a hostname of `"my_host"`.
|
|
|
|
local id = rednet.lookup("chat", "my_host")
|
|
if id then
|
|
print("Found my_host at computer #" .. id)
|
|
else
|
|
printError("Cannot find my_host")
|
|
end
|
|
|
|
]]
|
|
function lookup(protocol, hostname)
|
|
expect(1, protocol, "string")
|
|
expect(2, hostname, "string", "nil")
|
|
|
|
-- Build list of host IDs
|
|
local results = nil
|
|
if hostname == nil then
|
|
results = {}
|
|
end
|
|
|
|
-- Check localhost first
|
|
if hostnames[protocol] then
|
|
if hostname == nil then
|
|
table.insert(results, os.getComputerID())
|
|
elseif hostname == "localhost" or hostname == hostnames[protocol] then
|
|
return os.getComputerID()
|
|
end
|
|
end
|
|
|
|
if not isOpen() then
|
|
if results then
|
|
return table.unpack(results)
|
|
end
|
|
return nil
|
|
end
|
|
|
|
-- Broadcast a lookup packet
|
|
broadcast({
|
|
sType = "lookup",
|
|
sProtocol = protocol,
|
|
sHostname = hostname,
|
|
}, "dns")
|
|
|
|
-- Start a timer
|
|
local timer = os.startTimer(2)
|
|
|
|
-- Wait for events
|
|
while true do
|
|
local event, p1, p2, p3 = os.pullEvent()
|
|
if event == "rednet_message" then
|
|
-- Got a rednet message, check if it's the response to our request
|
|
local sender_id, message, message_protocol = p1, p2, p3
|
|
if message_protocol == "dns" and type(message) == "table" and message.sType == "lookup response" then
|
|
if message.sProtocol == protocol then
|
|
if hostname == nil then
|
|
table.insert(results, sender_id)
|
|
elseif message.sHostname == hostname then
|
|
return sender_id
|
|
end
|
|
end
|
|
end
|
|
elseif event == "timer" and p1 == timer then
|
|
-- Got a timer event, check it's the end of our timeout
|
|
break
|
|
end
|
|
end
|
|
if results then
|
|
return table.unpack(results)
|
|
end
|
|
return nil
|
|
end
|
|
|
|
local started = false
|
|
|
|
--- Listen for modem messages and converts them into rednet messages, which may
|
|
-- then be [received][`receive`].
|
|
--
|
|
-- This is automatically started in the background on computer startup, and
|
|
-- should not be called manually.
|
|
function run()
|
|
if started then
|
|
error("rednet is already running", 2)
|
|
end
|
|
started = true
|
|
|
|
while true do
|
|
local event, p1, p2, p3, p4 = os.pullEventRaw()
|
|
if event == "modem_message" then
|
|
-- Got a modem message, process it and add it to the rednet event queue
|
|
local modem, channel, reply_channel, message = p1, p2, p3, p4
|
|
if channel == id_as_channel() or channel == CHANNEL_BROADCAST then
|
|
if type(message) == "table" and type(message.nMessageID) == "number"
|
|
and message.nMessageID == message.nMessageID and not received_messages[message.nMessageID]
|
|
and (type(message.nSender) == "nil" or (type(message.nSender) == "number" and message.nSender == message.nSender))
|
|
and ((message.nRecipient and message.nRecipient == os.getComputerID()) or channel == CHANNEL_BROADCAST)
|
|
and isOpen(modem)
|
|
then
|
|
received_messages[message.nMessageID] = os.clock() + 9.5
|
|
if not prune_received_timer then prune_received_timer = os.startTimer(10) end
|
|
os.queueEvent("rednet_message", message.nSender or reply_channel, message.message, message.sProtocol)
|
|
end
|
|
end
|
|
|
|
elseif event == "rednet_message" then
|
|
-- Got a rednet message (queued from above), respond to dns lookup
|
|
local sender, message, protocol = p1, p2, p3
|
|
if protocol == "dns" and type(message) == "table" and message.sType == "lookup" then
|
|
local hostname = hostnames[message.sProtocol]
|
|
if hostname ~= nil and (message.sHostname == nil or message.sHostname == hostname) then
|
|
send(sender, {
|
|
sType = "lookup response",
|
|
sHostname = hostname,
|
|
sProtocol = message.sProtocol,
|
|
}, "dns")
|
|
end
|
|
end
|
|
|
|
elseif event == "timer" and p1 == prune_received_timer then
|
|
-- Got a timer event, use it to prune the set of received messages
|
|
prune_received_timer = nil
|
|
local now, has_more = os.clock(), nil
|
|
for message_id, deadline in pairs(received_messages) do
|
|
if deadline <= now then received_messages[message_id] = nil
|
|
else has_more = true end
|
|
end
|
|
prune_received_timer = has_more and os.startTimer(10)
|
|
end
|
|
end
|
|
end
|