ComputerCraft Wiki - User contributions [en]

Rednet (API)

2013-10-01T08:23:11Z

Engineer:

{{msgbox
|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]]
}}

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.

<table style="width: 100%; border: solid 1px black; margin: 2px; border-spacing: 0px;">
<tr><td colspan="2" style="font-weight: bold; font-size: large; padding-bottom: .3em; border-bottom: solid #C9C9C9 1px; background: #D3FFC2; line-height:28px;">
[[File:Grid_disk.png|24px]]  
Rednet (API)
</td></tr>

<tr><td style="width: 350px; background: #E0E0E0; padding: .4em; font-weight:bold;">Method Name</td><td style="background: #E0E0E0; padding: .4em; font-weight:bold;">Description</td></tr>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[rednet.open]]({{type|string}} side)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Tells the computer that the side can be used for networking.</td></tr>

<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[rednet.close]]({{type|string}} side)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Tells the computer that the side can no longer be used for networking.</td></tr>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[rednet.announce]]()</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Broadcasts an empty rednet message.</td></tr>

<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[rednet.send]]({{type|number}} receiverID, {{type|string}} message)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">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. The message must be a string to send across rednet, if you are wanting to send a table see [[textutils.serialize]]</td></tr>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[rednet.broadcast]]({{type|string}} message)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Sends the message to ALL connected and open computers.</td></tr>

<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[rednet.receive]]({{type|number}} timeout)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Waits until it received a rednet message or <var>timeout</var> has passed. Leave args empty to wait for a message forever.</td></tr>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[rednet.isOpen]]({{type|string}} side)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns true if the wireless modem is open.</td></tr>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[rednet.run]]()</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Runs rednet, but when it's already running it will error out.</td></tr>
</table>

==Events==
{| class="wikitable" width="100%"
! colspan="1" | Event Name
! colspan="1" | Description
! colspan="1" | Parameters
|-
! scope="row" | 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
|}

==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 ==
'''ID Whitelists are useless, and messages sent by Rednet can be viewed by anyone, even if they are not the target computer.'''

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.

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.

When using rednet for anything with security critical, be sure to implement your own security measures.

== Technical Details ==
'''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

(local) '''tValidSides''': Contains valid values of strings containing computer sides, used by ''open'' and ''close''

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

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

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

'''rednet.send(nRecipient, sMessage)''': For each side ''sSide'' in ''rs.getSides()'', it calls ''isOpen(sSide)''. If the result is true, it executes
peripheral.call( sSide, "transmit", nRecipient, os.getComputerID(), sMessage )

'''rednet.broadcast(sMessage)''': Calls ''send(CHANNEL_BROADCAST, sMessage)''

'''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

'''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
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
os.queueEvent( "rednet_message", sReplyChannel, sMessage, nDistance )

[[Category:APIs]]

Peripheral (API)

2013-09-03T13:48:46Z

Engineer:

__TOC__
The Peripheral API is for interacting with [[peripheral]]s connected to the computer, such as the [[Disk Drive]], the [[Advanced Monitor]] and [[Monitor]]. (More peripherals can be found under [[:Category:Peripherals|here]]).

Each peripheral block has a name, or ''side''. Although peripherals can now be attached to a computer using networking cables, the word ''side'' is a holdover from when peripherals needed to be directly next to the computer.

If the peripheral is next to the computer, its side is either "front", "back", "left", "right", "top" or "bottom". If the peripheral is attached by a cable, its side will follow the format "''type''_''id''", for example "printer_0".

Peripheral functions are called '''methods''', a term borrowed from Java.

{{API table|Peripheral|image=Grid disk.png|2=

{{API table/row|[[peripheral.isPresent]]({{type|string}} side)|{{type|boolean}}|
Returns '''true''' if a peripheral is connected on ''side''.
|odd}}

{{API table/row|[[peripheral.getType]]({{type|string}} side)|{{type|string}}/{{type|nil}}|
Returns the type of peripheral connected on ''side'', as a string.
If no peripheral is connected, returns nil.
}}

{{API table/row|[[peripheral.getMethods]]({{type|string}} side)|{{type|table}}/{{type|nil}}|
Returns a list of the names of all the methods of the peripheral connected on ''side''.
If no peripheral is connected, returns nil.
|odd}}

{{API table/row|[[peripheral.call]]({{type|string}} side, {{type|string}} method, ...)|any|
Calls a method on a peripheral. The arguments (apart from ''side'' and ''method'') and the return values depend on the method being called.
If no peripheral is connected, returns nil.
}}

{{API table/row|[[peripheral.wrap]]({{type|string}} side)|{{type|table}}/{{type|nil}}|
Returns a table of functions, allowing you to call peripheral methods as if they were normal Lua functions.
If no peripheral is connected, returns nil.
|odd}}

{{API table/row|[[peripheral.getNames]]()|{{type|table}}|
This function returns a table of all the sides that have a peripheral present. If the present peripheral is a wired modem any names of the peripherals that is on the network are also added to the table.
|odd}}

}}

==Connecting peripherals using networking cables==
Using Networking Cables, you can attach and use peripherals without having them directly touching the computer. To connect a peripheral in this way, place a Wired Modem on any side of your computer, as you would a [[Wireless Modem]]. Place a Wired Modem on each peripheral you wish to connect, and then connect all of them with Networking Cables. Then right click each of the wired modems.

You should receive a message in your chat bar for each peripheral informing you of a successful connection, and the peripheral side.

==Monitor==
[[Monitor#Peripheral_Functions|Monitor Peripheral functions]] have been moved to the [[Monitor]] page.
In addition, the [[Advanced_Monitor#Peripheral_Functions|Advanced Monitor Peripheral functions]] have been moved to the [[Advanced Monitor]] page.

==Printer==
[[Printer#Peripheral_Functions|Printer Peripheral functions]] have been moved to the [[Printer]] page.

==Computers==
[[Computer#Peripheral_Functions|Computer Peripheral functions]] have been moved to the [[Computer]] page.
In addition, the [[Advanced_Computer#Peripheral_Functions|Advanced Computer Peripheral functions]] have been moved to the [[Advanced Computer]] page.

[[Category:APIs]]

Os.pullEvent

2013-04-30T17:30:09Z

Engineer: /* Event types */

{{lowercase}}
{{Function
|name=os.pullEvent
|args=[{{type|string}} filter]
|api=OS
|returns={{type|string}} event, variable parameters(see table below)
|addon=ComputerCraft
|desc=Waits (yields) until an event occurs
|examples=
{{Example
|desc=The program requires to wait for a keypress to do something:
|code=[[Function (type)|function]] clear()
[[term.clear]]()
[[term.setCursorPos]] (1,1)
end
while true do
clear()
[[print]] ("Press E to do something.")
local event, param1 = os.pullEvent ("char") -- limit os.pullEvent to the char event
if param1 == "e" then -- if the returned value was 'e'
clear()
[[write]] ("Name: ")
local name = [[read]]()
[[print]] (name)
break
else
clear()
[[print]] ("Wrong button!")
[[os.sleep|sleep]] (1.5) -- I don't like a whole 2 seconds but 1 second is too short
end
end
}}
{{Example
|desc=This script shows how the os.pullEvent function can be used as an iterator instead of using a while loop:
|code=for event, param1 in os.pullEvent do --this will continuously fire an event without the use of a while loop
[[print]]("Event: "..event)
[[print]]("Param1: "..param1)
end
[[User:SuicidalSTDz|SuicidalSTDz]] 20:23, 29 March 2013 (MSK)
}}
}}

=== Common syntax ===

event, param1, param2, param3 = os.pullEvent()

Note: This is one of the most commonly used functions that can return multiple values.
It works like any other function call (such as "input = read()") except that you can get more than one piece of information back.

== How it works ==
When os.pullEvent() is called, the computer waits until an event occurs.
Events can be triggered by several different things, such as a key being pressed or a redstone input changing.
They are usually triggered by ComputerCraft itself, when it needs to notify the computer that something happened.
They can also be triggered by peripherals, or by your program calling [[os.queueEvent]].

More complicated input, such as "the user typing a line of text," does ''not'' correspond to an event.
[[read]] handles this inside itself by waiting for the user to press a key, then updating the screen, moving the cursor, etc.

Events have a type (which is a string) and 0-5 parameters (which are often but not always strings).
No built-in events use more than 3 parameters.

When an event occurs, the event type, followed by the parameters, will be returned. If you have:

event, button, x, y = os.pullEvent()

and the user clicks the mouse at coordinates 5,4 then:
* event will be set to "mouse_click" (the event type)
* button will be set to 0 (the first parameter)
* x will be set to 5 (the second parameter)
* y will be set to 4 (the third parameter)

Note that in this example, we didn't specify a filter. If you specify a filter, then all events of different types will be ignored.
If the user inserts a disk, instead of clicking the mouse, then event will be "disk", button will be the side the disk drive is on, and x and y will be nil.

If we wanted to only wait for mouse clicks we could use:

event, button, x, y = os.pullEvent("mouse_click")

which will ignore any events that are not mouse clicks.

If you assign more variables than necessary, the extra ones will be set to nil.
If you assign fewer variables than necessary, the extra parameters will be discarded.

==Event types==
{| class="wikitable" width="100%"
! rowspan="2" | Name
! rowspan="2" | Description
! colspan="3" | Parameters
|-
! 1 !! 2 !! 3
|-
! scope="row" | [[char (event)|char]]
|Fired when text is typed on the keyboard
| {{type|string}} the letter typed
|
|
|-
! scope="row" | [[key (event)|key]]
|Fired when a key is pressed on the keyboard
|{{type|number}} numerical keycode
|
|
|-
! scope="row" | [[timer (event)|timer]]
|Fired when a timeout started by [[os.startTimer]]() completes
|{{type|number}} Value of the timer as returned by os.startTimer()
|
|
|-
! scope="row" | [[alarm (event)|alarm]]
|Fired when a time passed to [[os.setAlarm]]() is reached
|{{type|number}} Value of the alarm as returned by os.setAlarm()
|
|
|-
! scope="row" | [[redstone (event)|redstone]]
|Fired when the state of any of the redstone inputs change
|
|
|
|-
! scope="row" | [[terminate (event)|terminate]]
|Fired when a combination of keys CTRL and T is pressed and held for three seconds.
You will not normally see this event, as it is handled inside os.pullEvent.
|
|
|
|-
! scope="row" | [[disk (event)|disk]]
|Fired when a disk is inserted into an adjacent disk drive
|{{type|string}} side
|
|
|-
! scope="row" | [[disk_eject (event)|disk_eject]]
|Fired when a disk is removed from an adjacent disk drive
|{{type|string}} side
|
|
|-
! scope="row" | [[peripheral (event)|peripheral]]
|Fired when peripheral is attached
|{{type|string}} side
|
|
|-
! scope="row" | [[peripheral_detach (event)| peripheral_detach]]
|Fired when peripheral is removed
|{{type|string}} side
|
|
|-
! scope="row" | [[rednet_message (event)|rednet_message]]
|Fired when a rednet message is received from the [[Rednet_(API)|rednet API]]
|{{type|number}} senderID
|{{type|string}} message
|{{type|number}} distance travelled
|-
! scope="row" | [[http_success (event)|http_success]]
|Fired when an attempt to receive text from / post text on a website is successful.
You will not normally see this event as it is handled inside http.get.
|{{type|string}} url of the site
|{{type|table}} text on the site
|
|-
! scope="row" | [[http_failure (event)|http_failure]]
|Fired when an attempt to receive text from / post text on a website is unsuccessful
You will not normally see this event as it is handled inside http.get.
|{{type|string}} url of the site
|
|
|-
! scope="row" | [[mouse_click (event)|mouse_click]]
|Fired when a mouse button is pressed
|{{type|number}} mouse button
|{{type|number}} x coordinate
|{{type|number}} y coordinate
|-
! scope="row" | [[mouse_scroll (event)|mouse_scroll]]
|Fired when a mousewheel is scrolled.
|{{type|number}} scroll direction (-1 for up, 1 for down)
|{{type|number}} x coordinate(in screen chars)
|{{type|number}} y coordinate(in screen chars)
|-
! scope="row" | [[mouse_drag (event)|mouse_drag]]
|Fired when the mouse is moved after clicking.
|{{type|number}} mouse button
|{{type|number}} x coordinate(in screen chars)
|{{type|number}} y coordinate(in screen chars)
|-
! scope="row" | [[monitor_touch (event)|monitor_touch]]
|Fired when a player right click on an advanced monitor connected.
|{{type|string}} side
|{{type|number}} x coordinate(in screen chars)
|{{type|number}} y coordinate(in screen chars)
|-
! scope="row" | [[monitor_resize (event)|monitor_resize]]
|Fired when a monitor resizes
|{{type|string}} side
|
|
|}

== Guides ==
[http://www.computercraft.info/forums2/index.php?/topic/1516-ospullevent-what-is-it-and-how-is-it-useful/page__view__findpost__p__11156 ''Onionnion's Guide on os.pullEvent()'']

[[Category:Lua_Core_Functions]]