Difference between revisions of "Rednet (API)"

From ComputerCraft Wiki
Jump to: navigation, search
m (Deprecated Functions)
m (hostname is optional in rednet.lookup, page now reflects this)
 
(5 intermediate revisions by 2 users not shown)
Line 3: Line 3:
 
The Rednet API allows systems to communicate between each other without using redstone. It serves as a wrapper for the [[modem (API)|modem API]], offering ease of functionality (particularly in regards to [[Repeat|repeating signals]]) with some expense of fine control.  
 
The Rednet API allows systems to communicate between each other without using redstone. It serves as a wrapper for the [[modem (API)|modem API]], offering ease of functionality (particularly in regards to [[Repeat|repeating signals]]) with some expense of fine control.  
  
In order to send and receive data, a [[modem]] (either [[Wired Modem|wired]] or [[Wireless Modem|wireless]]) is required. The data reaches any possible destinations immediately after sending it, but is [[#Range|range limited]].
+
In order to send and receive data, a [[modem]] (either [[Wired Modem|wired]], [[Wireless Modem|wireless]], or [[Ender Modem|ender]]) is required. The data reaches any possible destinations immediately after sending it, but is [[#Range|range limited]].
  
  
Line 21: Line 21:
  
 
{{API table/row
 
{{API table/row
|[[rednet.send]]({{type|number}} receiverID, {{type|string}} message, [<nowiki/>{{type|string}} protocol])
+
|[[rednet.send]]({{type|number}} receiverID, {{type|any}} message, [<nowiki/>{{type|string}} protocol])
 
|{{type|nil}}
 
|{{type|nil}}
|Sends a message "intended" for another system with a specific ID, using the currently opened sides. The <var>receiverID</var> is the ID {{type|number}} (note - '''not''' a {{type|string}}) of the computer you're sending the message to. Later versions or ComputerCraft allow some other data types as the message.}}
+
|Sends a message "intended" for another system with a specific ID, using the currently opened sides. The <var>receiverID</var> is the ID {{type|number}} (note - '''not''' a {{type|string}}) of the computer you're sending the message to. The [[Variables|types]] that can be sent as the message vary depending on the version of ComputerCraft in use.}}
  
 
{{API table/row
 
{{API table/row
|[[rednet.broadcast]]({{type|string}} message, [<nowiki/>{{type|string}} protocol])
+
|[[rednet.broadcast]]({{type|any}} message, [<nowiki/>{{type|string}} protocol])
 
|{{type|nil}}
 
|{{type|nil}}
 
|Sends the message to ''all'' connected and open computers.
 
|Sends the message to ''all'' connected and open computers.
Line 33: Line 33:
 
{{API table/row
 
{{API table/row
 
|[[rednet.receive]]([<nowiki/> [<nowiki/>{{type|string}} protocolFilter, ] {{type|number}} timeout])
 
|[[rednet.receive]]([<nowiki/> [<nowiki/>{{type|string}} protocolFilter, ] {{type|number}} timeout])
|{{type|number}} senderID, {{type|string}} message, {{type|number}} distance / {{type|string}} protocol
+
|{{type|number}} senderID, {{type|any}} message, {{type|number}} distance / {{type|string}} protocol
 
|Waits until a rednet message of the specified protocol has been received, or until <var>timeout</var> 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)|Modem API]].}}
 
|Waits until a rednet message of the specified protocol has been received, or until <var>timeout</var> 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)|Modem API]].}}
  
Line 54: Line 54:
  
 
{{API table/row
 
{{API table/row
|[[rednet.lookup]]({{type|string}} protocol, {{type|string}} hostname)
+
|[[rednet.lookup]]({{type|string}} protocol, <nowiki/>[<nowiki/>{{type|string}} hostname<nowiki/>]<nowiki/>)
 
|{{type|number}} ID1, {{type|number}} ID2, ...
 
|{{type|number}} ID1, {{type|number}} ID2, ...
 
|Searches the local network for systems registered with a matching <var>hostname</var> and/or <var>protocol</var>, and returns matching IDs found. '''Only available in ComputerCraft 1.6 and above.'''
 
|Searches the local network for systems registered with a matching <var>hostname</var> and/or <var>protocol</var>, and returns matching IDs found. '''Only available in ComputerCraft 1.6 and above.'''
Line 66: Line 66:
  
 
}}
 
}}
 
  
 
==Events==
 
==Events==
Line 72: Line 71:
 
|desc=Fired when a rednet message is received (can be pulled via [[os.pullEvent|os.pullEvent()]] directly as an alternative to using [[rednet.receive|rednet.receive()]]).
 
|desc=Fired when a rednet message is received (can be pulled via [[os.pullEvent|os.pullEvent()]] directly as an alternative to using [[rednet.receive|rednet.receive()]]).
 
|return1={{type|number}} senderId
 
|return1={{type|number}} senderId
|return2={{type|string}} message
+
|return2={{type|any}} message
 
|return3={{type|number}} distance / {{type|string}} protocol
 
|return3={{type|number}} distance / {{type|string}} protocol
 
}}
 
}}
Line 82: Line 81:
 
  minRange + (position.yCoord - 96.0) * ((maxRange - minRange) / ((world.getHeight() - 1) - 96.0))
 
  minRange + (position.yCoord - 96.0) * ((maxRange - minRange) / ((world.getHeight() - 1) - 96.0))
  
Where, by default:
+
Where, for a [[Wireless Modem]]:
  
 
  minRange = 64  (or 16 in a storm)
 
  minRange = 64  (or 16 in a storm)
 
  maxRange = 384 (or 96 in a storm)
 
  maxRange = 384 (or 96 in a storm)
 
  world.getHeight() = 256
 
  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.
 
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.
Line 95: Line 96:
  
 
As of ComputerCraft 1.6, a [[Repeat|repeater script]] is available to all systems by default.
 
As of ComputerCraft 1.6, a [[Repeat|repeater script]] is available to all systems by default.
 
  
 
==Protocols==
 
==Protocols==
Introduced by ComputerCraft 1.6, "protocols" are simple string names indicating what given 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 [[rednet.lookup|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.
+
Introduced by ComputerCraft 1.6, "protocols" are simple string names indicating what [[rednet.send|sent messages]] are about. [[rednet.receive|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 [[rednet.lookup|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==
 
==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 [http://www.eloraam.com RedPower]. That also allowed communication between computers, but the data was transferred slowly - every bit was converted to redstone signal (using the [[redstone (API)|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 Modem|wireless networking]] to the mod and allowed instant communications between computers.
+
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 [http://www.eloraam.com RedPower]. That also allowed communication between computers, but the data was transferred slowly - every bit was converted to redstone signal (using the [[redstone (API)|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 Modem|wireless networking]] to the mod and allowed instant communications between computers.
  
 
Later, ComputerCraft 1.51 brought forward [[Wired Modem]]s, which could not only be used for regular network communications, but to interact with [[peripheral]]s remotely.
 
Later, ComputerCraft 1.51 brought forward [[Wired Modem]]s, which could not only be used for regular network communications, but to interact with [[peripheral]]s remotely.

Latest revision as of 16:59, 15 January 2018

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

Grid disk.png  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


Grid Modem.png  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 .
Grid disk.png  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()