Difference between revisions of "Rednet (API)"

From ComputerCraft Wiki
Jump to: navigation, search
m (Events fix.)
m (hostname is optional in rednet.lookup, page now reflects this)
 
(41 intermediate revisions by 17 users not shown)
Line 1: Line 1:
The rednet API allows computers to communicate between themselves without using redstone wires. In order to send and receive data, a [[modem]] is required. The data is received immediately after sending it, but only by computers within a certain range. That range depends on the altitude of the sending computer increasing with higher altitudes to a max of 384.
+
''For a tutorial on how to use the API, visit [[Rednet Tutorial]].''
  
==History==
+
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.  
Before the creation of the in-game wireless networking API, the term "Rednet" referred to a system created by one of the ComputerCraft users based on bundled cables from a popular Minecraft mod - RedPower. It also allowed communication between computers, but the data was transferred slowly - every bit was converted to redstone signal, that lasted about 0,1 seconds. On the release of ComputerCraft 1.3, the system became useless, as the wireless networking was officially implemented to the mod.
+
  
==Methods==
+
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]].
{| border="1" cellpadding="5" cellspacing="0"
+
 
!style="background:#EEE" width="200px"|Method name
+
 
!style="background:#EEE" width="*"|Description
+
==API==
!style="background:#EEE" width="80px"|Return type
+
{{API table|rednet|image=Grid_disk.png|2=
|-
+
 
|[[rednet.open]](side)
+
{{API table/row
|Tells the computer that the side can be used for networking.
+
|[[rednet.open]]({{type|string}} side)
|nil
+
|{{type|nil}}
|-
+
|Tells the computer that the side can be used for networking.}}
|[[rednet.close]](side)
+
 
 +
{{API table/row
 +
|[[rednet.close]]({{type|string}} side)
 +
|{{type|nil}}
 
|Tells the computer that the side can no longer be used for networking.
 
|Tells the computer that the side can no longer be used for networking.
|nil
+
|odd}}
|-
+
 
|[[rednet.announce]]()
+
{{API table/row
|Broadcasts an empty rednet message.
+
|[[rednet.send]]({{type|number}} receiverID, {{type|any}} message, [<nowiki/>{{type|string}} protocol])
|success
+
|{{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. The [[Variables|types]] that can be sent as the message vary depending on the version of ComputerCraft in use.}}
|[[rednet.send]](receiverID, message)
+
 
|Sends a message to the computer using the opened sides. The receiver ID is the ID (number, not string) of the computer you're sending the message to. ID as nil will do the same as a broadcast.
+
{{API table/row
|success
+
|[[rednet.broadcast]]({{type|any}} message, [<nowiki/>{{type|string}} protocol])
|-
+
|{{type|nil}}
|[[rednet.broadcast]](message)
+
|Sends the message to ''all'' connected and open computers.
|Sends the message to ALL connected and open computers.
+
|odd}}
|success
+
 
|-
+
{{API table/row
|[[rednet.receive]](timeout)
+
|[[rednet.receive]]([<nowiki/> [<nowiki/>{{type|string}} protocolFilter, ] {{type|number}} timeout])
|Waits until it received a rednet message or <var>timeout</var> has passed. Leave args empty to wait for a message forever.
+
|{{type|number}} senderID, {{type|any}} message, {{type|number}} distance / {{type|string}} protocol
|senderId, message, distance
+
|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]].}}
|-
+
 
|rednet.isOpen(side)
+
{{API table/row
|Returns true if the wireless modem is open or nil if not. Returns 1 always.
+
|[[rednet.isOpen]]({{type|string}} side)
|Boolean, integer
+
|{{type|boolean}} isOpen
|}
+
|Returns [[Boolean_(type)|true]] if the wireless modem is open.
 +
|odd}}
 +
 
 +
{{API table/row
 +
|[[rednet.host]]({{type|string}} protocol, {{type|string}} hostname)
 +
|{{type|nil}}
 +
|Registers <var>hostname</var> against <var>protocol</var> for the purposes of [[rednet.lookup]](). '''Only available in ComputerCraft 1.6 and above.'''}}
 +
 
 +
{{API table/row
 +
|[[rednet.unhost]]({{type|string}} protocol, {{type|string}} hostname)
 +
|{{type|nil}}
 +
|Unregisters <var>hostname</var> from <var>protocol</var>. '''Only available in ComputerCraft 1.6 and above.'''
 +
|odd}}
 +
 
 +
{{API table/row
 +
|[[rednet.lookup]]({{type|string}} protocol, <nowiki/>[<nowiki/>{{type|string}} hostname<nowiki/>]<nowiki/>)
 +
|{{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.'''
 +
}}
 +
 
 +
{{API table/row
 +
|[[rednet.run]]()
 +
|{{type|nil}}
 +
|Internal use function - runs automatically and does not need to be called directly. Waits for [[Modem_message_(event)|modem_message]] events to appear within the event queue and generates corresponding [[Rednet_message_(event)|rednet_message]] events for use with this API. Also responds to [[rednet.lookup]]() requests.
 +
|odd}}
 +
 
 +
}}
  
 
==Events==
 
==Events==
{| border="1" cellpadding="2" cellspacing="0"
+
{{Event|name=[[rednet_message_(event)|rednet_message]]
!style="background:#EEE" width="200px"|Event name
+
|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()]]).
!style="background:#EEE" width="*"|Description
+
|return1={{type|number}} senderId
!style="background:#EEE" width="*"|Parameters
+
|return2={{type|any}} message
|-
+
|return3={{type|number}} distance / {{type|string}} protocol
|rednet_message
+
}}
|Fired when a rednet message is received (can be used as alternative for rednet.receive())
+
 
|senderId, message, distance
+
 
 +
==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 [[Networking_Cable|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 [[Repeat|repeater script]] is available to all systems by default.
 +
 
 +
==Protocols==
 +
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==
 +
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.
 +
 
 +
 
 +
==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)|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==
 +
{{Deprecated
 +
|plural=yes
 +
|type=These functions
 +
}}
 +
 
 +
{{API table|Deprecated Rednet Functions|image=Grid disk.png|2=
 +
 
 +
{{API table/row
 +
|[[rednet.announce]]()
 +
|{{type|nil}}
 +
|Broadcasts an empty rednet message. Removed from ComputerCraft by version ''1.5'' in favor of [[rednet.broadcast]]()
 +
|odd}}
 +
 
 +
}}
 +
 
 
[[Category:APIs]]
 
[[Category:APIs]]

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()