Rednet (API)

For a tutorial on how to use the API, visit Rednet Tutorial.

The Rednet API allows systems to communicate between each other without using redstone. It serves as a wrapper for the modem API, offering ease of functionality (particularly in regards to repeating signals) with some expense of fine control.

In order to send and receive data, a modem (either wired, wireless, or ender) is required. The data reaches any possible destinations immediately after sending it, but is range limited.

API

rednet (API)
Function	Return values	Description
rednet.open(string side)	nil	Tells the computer that the side can be used for networking.
rednet.close(string side)	nil	Tells the computer that the side can no longer be used for networking.
rednet.send(number receiverID, any message, [string protocol])	nil	Sends a message "intended" for another system with a specific ID, using the currently opened sides. The receiverID is the ID number (note - not a string) of the computer you're sending the message to. The types that can be sent as the message vary depending on the version of ComputerCraft in use.
rednet.broadcast(any message, [string protocol])	nil	Sends the message to all connected and open computers.
rednet.receive([ [string protocolFilter, ] number timeout])	number senderID, any message, number distance / string protocol	Waits until a rednet message of the specified protocol has been received, or until timeout seconds have passed. Leave all arguments empty to wait for any message indefinitely. If only a single, numerical argument is passed, will wait that many seconds for a message of any protocol. Versions of ComputerCraft prior to 1.6 may return the distance to the transmitting computer - 1.6 or later returns message protocols instead, though distance can still be obtained via direct use of the Modem API.
rednet.isOpen(string side)	boolean isOpen	Returns true if the wireless modem is open.
rednet.host(string protocol, string hostname)	nil	Registers hostname against protocol for the purposes of rednet.lookup(). Only available in ComputerCraft 1.6 and above.
rednet.unhost(string protocol, string hostname)	nil	Unregisters hostname from protocol. Only available in ComputerCraft 1.6 and above.
rednet.lookup(string protocol, [string hostname])	number ID1, number ID2, ...	Searches the local network for systems registered with a matching hostname and/or protocol, and returns matching IDs found. Only available in ComputerCraft 1.6 and above.
rednet.run()	nil	Internal use function - runs automatically and does not need to be called directly. Waits for modem_message events to appear within the event queue and generates corresponding rednet_message events for use with this API. Also responds to rednet.lookup() requests.

Events

Event rednet_message
Fired when a rednet message is received (can be pulled via os.pullEvent() directly as an alternative to using rednet.receive()).
Returned Object 1	number senderId
Returned Object 2	any message
Returned Object 3	number distance / string protocol

Range

The range of a wireless network transmission can be determined via the following formula:

minRange + (position.yCoord - 96.0) * ((maxRange - minRange) / ((world.getHeight() - 1) - 96.0))

Where, for a Wireless Modem:

minRange = 64  (or 16 in a storm)
maxRange = 384 (or 96 in a storm)
world.getHeight() = 256

For an Ender Modem, the maximum range is thought to be 2,147,483,647 blocks. It's unknown if this is affected by world height or weather.

Catch is, that formula is quite capable of returning values that are well below 0... More research is required, it seems. Anyway, min/max range figures can be altered in ComputerCraft.cfg, and the maximum range of a system located at world height will generally be equal to the maxRange for the current weather.

Even for the purposes of two-way communications, only the system with the best range is checked - a system located at the bottom of the world may hence send to and receive from a system at the top. Range is calculated in three dimensions, so the area a given system can reach wirelessly is represented by a sphere.

For wired networks, range between devices is 256 blocks of network cable (unconfigurable). Either method of communication works regardless as to whether the intervening chunks are loaded or not.

As of ComputerCraft 1.6, a repeater script is available to all systems by default.

Protocols

Introduced by ComputerCraft 1.6, "protocols" are simple string names indicating what sent messages are about. Receiving systems may filter messages according to their protocols, thereby automatically ignoring incoming messages which don't specify an identical string. It's also possible to lookup which systems in the area are interested in certain protocols, hence making it easier to determine where given messages should be sent in the first place.

History

Before the creation of the in-game wireless networking API, the term "Rednet" referred to a system created by a ComputerCraft user based on bundled cables from the popular Minecraft mod RedPower. That also allowed communication between computers, but the data was transferred slowly - every bit was converted to redstone signal (using the redstone API) that lasted about 0.05 seconds (the length of a Minecraft "tick"). That system was rendered redundant by the release of ComputerCraft 1.3, as this heralded the arrival of wireless networking to the mod and allowed instant communications between computers.

Later, ComputerCraft 1.51 brought forward Wired Modems, which could not only be used for regular network communications, but to interact with peripherals remotely.

Security

In current versions of ComputerCraft (1.5 or later), Rednet is not to be considered a "secure" method of communication. The identity data indicating who sent a given message is set by the sender, and hence cannot be trusted. Messages intended for a given system may be received and read by any other system in range.

This is because Rednet is simply a convenience wrapper for the modem API, and while it typically sends/receives using channel numbers matching the IDs of systems you control, the latter offers complete control over channel usage. Another user can hence easily task the modem API directly to sniff and find out what messages a computer is receiving if he knows (or can even guess) its ID, or pretend to send from any ID he wishes.

When using Rednet for anything with security implications, be sure to implement your own methods of protection.

Deprecated Functions

These functions have been deprecated. These functions have been removed from ComputerCraft .

Deprecated Rednet Functions (API)
Function	Return values	Description
rednet.announce()	nil	Broadcasts an empty rednet message. Removed from ComputerCraft by version 1.5 in favor of rednet.broadcast()