Difference between revisions of "Rednet (API)"

From ComputerCraft Wiki
Jump to: navigation, search
m (API)
m (hostname is optional in rednet.lookup, page now reflects this)
 
(15 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{NeedsWork|Could use more information re protocols outside of the API section. - [[User:Bomb Bloke|BB]]}}
+
''For a tutorial on how to use the API, visit [[Rednet Tutorial]].''
  
{{msgbox
+
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.  
|title=Please Note
+
 
|text=Rednet no longer supports transmitting data through Bundled Cables. However, interacting with Bundled Cables is still available via the [[Redstone_(API)|Redstone API]].
+
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]].
}}
+
  
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.
 
'''NOTE:''' The distance variable that is sent/received through the Rednet API is based off of the computer location, not the modem location.
 
  
 
==API==
 
==API==
{| class="wikitable"
+
{{API table|rednet|image=Grid_disk.png|2=
! width="100px" | Returns
+
 
! width="200px" | Method name
+
{{API table/row
! Description
+
! Min version
+
|-
+
|
+
 
|[[rednet.open]]({{type|string}} side)
 
|[[rednet.open]]({{type|string}} side)
|Tells the computer that the side can be used for networking.
+
|{{type|nil}}
|
+
|Tells the computer that the side can be used for networking.}}
|-
+
 
|
+
{{API table/row
 
|[[rednet.close]]({{type|string}} side)
 
|[[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.
|
+
|odd}}
|-
+
 
|
+
{{API table/row
|[[rednet.announce]]()
+
|[[rednet.send]]({{type|number}} receiverID, {{type|any}} message, [<nowiki/>{{type|string}} protocol])
|Broadcasts an empty rednet message. Removed from ComputerCraft by version ''???'' in favour of [[rednet.broadcast|rednet.broadcast()]].
+
|{{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.}}
|-
+
 
|
+
{{API table/row
|[[rednet.send]]({{type|number}} receiverID, {{type|string}} message, [<nowiki></nowiki>{{type|string}} protocol])
+
|[[rednet.broadcast]]({{type|any}} message, [<nowiki/>{{type|string}} protocol])
|Sends a message "intended" for another system with a specific ID, using the currently opened sides. The receiver ID is the ID number (note - not a string) of the computer you're sending the message to. Later versions or ComputerCraft allow some other data types as the message.
+
|{{type|nil}}
|
+
|Sends the message to ''all'' connected and open computers.
|-
+
|odd}}
|
+
 
|[[rednet.broadcast]]({{type|string}} message, [<nowiki></nowiki>{{type|string}} protocol])
+
{{API table/row
|Sends the message to ALL connected and open computers.
+
|[[rednet.receive]]([<nowiki/> [<nowiki/>{{type|string}} protocolFilter, ] {{type|number}} timeout])
|
+
|{{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]].}}
|{{type|number}} senderID, {{type|string}} message, {{type|number}} distance / {{type|string}} protocol
+
 
|[[rednet.receive]]([<nowiki></nowiki>{{type|string}} protocolFilter], [<nowiki></nowiki>{{type|number}} timeout])
+
{{API table/row
|Waits until it received a rednet message of the specified protocol has been received, or until <var>timeout</var> seconds have passed. Leave args 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]].
+
|
+
|-
+
|{{type|boolean}} isOpen
+
 
|[[rednet.isOpen]]({{type|string}} side)
 
|[[rednet.isOpen]]({{type|string}} side)
|Returns true if the wireless modem is open.
+
|{{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)
 
|[[rednet.host]]({{type|string}} protocol, {{type|string}} hostname)
|Registers ''hostname'' against ''protocol'' for the purposes of [[rednet.lookup|rednet.lookup()]].
+
|{{type|nil}}
|1.6
+
|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)
 
|[[rednet.unhost]]({{type|string}} protocol, {{type|string}} hostname)
|Unregisters ''hostname'' from ''protocol''.
+
|{{type|nil}}
|1.6
+
|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, ...
 
|{{type|number}} ID1, {{type|number}} ID2, ...
|[[rednet.lookup]]({{type|string}} protocol, {{type|string}} hostname)
+
|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 name and/or protocol, and returns information including (but not always limited to) their IDs.
+
}}
|1.6
+
 
|-
+
{{API table/row
|
+
 
|[[rednet.run]]()
 
|[[rednet.run]]()
|Internal use function - runs automatically and need not 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|rednet.lookup()]] requests.
+
|{{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==
{| class="wikitable" width="100%"
+
{{Event|name=[[rednet_message_(event)|rednet_message]]
! colspan="1" | 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()]]).
! colspan="1" | Description
+
|return1={{type|number}} senderId
! colspan="1" | Parameters
+
|return2={{type|any}} message
|-
+
|return3={{type|number}} distance / {{type|string}} protocol
! scope="row" | [[Rednet_message_(event)|rednet_message]]
+
}}
|Fired when a rednet message is received (can be used as alternative for rednet.receive())
+
|{{type|number}} senderId, {{type|string}} message, {{type|number}} distance / {{type|string}} protocol
+
|}
+
  
==History==
 
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,05 seconds. On the release of ComputerCraft 1.3, the system became useless, as the wireless networking was officially implemented to the mod.
 
  
== Security ==
+
==Range==
'''ID Whitelists are useless, and messages sent by Rednet can be viewed by anyone, even if they are not the target computer.'''
+
The range of a wireless network transmission can be determined via the following formula:
  
Rednet alone is completely insecure. Any messages sent via rednet can actually be sniffed, contrary to popular belief, and people can pretend to be a certain computer and fool rednet easily.  
+
minRange + (position.yCoord - 96.0) * ((maxRange - minRange) / ((world.getHeight() - 1) - 96.0))
  
Rednet simply utilizes the Modem API. A user can easily sniff and find out what messages a computer is receiving if he knows its ID. All he has to do is use the [[Modem_(API)|Modem API]] to listen, where the channel to listen on is the target computer's ID. Additionally, a malicious user can 'pretend' to be a certain computer by using the Modem API to send a message to the target computer's ID with the message, but using the ID of the computer to pretend to be for the reply channel parameter. If they do so, the computer receiving the message with rednet will be fooled into thinking it came from a different computer.
+
Where, for a [[Wireless Modem]]:
  
When using rednet for anything with security critical, be sure to implement your own security measures.
+
minRange = 64  (or 16 in a storm)
 +
maxRange = 384 (or 96 in a storm)
 +
world.getHeight() = 256
  
== Technical Details ==
+
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.
'''Overview''': Rednet functions by having a modem listen on the channel of the computer's ID, and the rednet broadcast channel for messages. It uses the ''replyChannel'' parameter of the modem_message event as the sender computer's ID. It broadcasts by sending a simple modem message on the rednet broadcast channel, and receives by receiving a modem message on the broadcast channel or the channel of its computer's ID.  
+
  
'''CHANNEL_BROADCAST''': 65535
+
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.
  
(local) '''tValidSides''': Contains valid values of strings containing computer sides, used by ''open'' and ''close''
+
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.
  
'''rednet.open(sSide)''': Checks if ''sSide'' is a string, a valid side, and a side with a modem on it. Then it opens the modem on ''CHANNEL_BROADCAST'' and ''os.getComputerID()''
+
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.
  
'''rednet.close(sSide)''': Checks if ''sSide'' is a string, a valid side, and a side with a modem on it. Then it closes the modem on ''CHANNEL_BROADCAST'' and ''os.getComputerID()''
+
As of ComputerCraft 1.6, a [[Repeat|repeater script]] is available to all systems by default.
  
'''rednet.isOpen(sSide)''': Checks if ''sSide'' is a string, a valid side, and a side with a modem on it. Then it returns true if the modem on ''sSide'' is open on both ''CHANNEL_BROADCAST'' and ''os.getComputerID()''
+
==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.
  
'''rednet.send(nRecipient, sMessage)''': For each side ''sSide'' in ''rs.getSides()'', it calls ''isOpen(sSide)''. If the result is true, it executes
+
==History==
peripheral.call( sSide, "transmit", nRecipient, os.getComputerID(), sMessage )
+
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.
  
'''rednet.broadcast(sMessage)''': Calls ''send(CHANNEL_BROADCAST, sMessage)''
+
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.
  
'''rednet.receive(nTimeout)''': If ''nTimeout'' is there, it starts a timer for ''nTimeout'' seconds-stored in ''timer'', and sets ''sFilter'' to nil. Otherwise, ''sFilter'' is set to "rednet_message". In a loop,
 
local e, p1, p2, p3, p4, p5 = os.pullEvent( sFilter )
 
is called. If ''e'' is "rednet_message" then it returns ''p1'', ''p2'', and ''p3'', but if ''e'' is "timer", and ''p1'' is ''timer'' then it returns nil.
 
  
(local) '''bRunning''': false
+
==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.
  
'''rednet.run()''': If ''bRunning'' is true, then it errors "rednet is already running". It then sets ''bRunning'' to true to indicate that it is running. Looping while ''bRunning'', it pulls
+
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.
local sEvent, sSide, sChannel, sReplyChannel, sMessage, nDistance = os.pullEventRaw( "modem_message" )
+
 
Then if ''sEvent'' is "modem_message", ''isOpen(sSide)'' is true, and ''sChannel'' is ''os.getComputerID()'' or it is ''CHANNEL_BROADCAST'', then it queues
+
When using Rednet for anything with security implications, be sure to implement your own methods of protection.
os.queueEvent( "rednet_message", sReplyChannel, sMessage, nDistance )
+
 
 +
 
 +
==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()