Difference between revisions of "Modem (API)"

From ComputerCraft Wiki
Jump to: navigation, search
(Added NeedsWork tag)
m (Changing context: 'I will' => 'the modem will'.)
Line 5: Line 5:
 
With the advent of ComputerCraft 1.5, the behavior of modems has changed somewhat drastically. Although the Rednet API still has the same functionality, it is really just a wrapper for what is a completely different system underneath.
 
With the advent of ComputerCraft 1.5, the behavior of modems has changed somewhat drastically. Although the Rednet API still has the same functionality, it is really just a wrapper for what is a completely different system underneath.
  
The major change introduced to modems in this version of ComputerCraft is channels: Channels are essentially open networks which can be opened, closed, and listened on by any computer within range. To interact with channels, one must wrap/interact directly with the peripheral as opposed to the previous interaction with the rednet API.
+
The major change introduced to modems in this version of ComputerCraft is channels - channels are essentially networks which can be opened, closed and listened on by any computer within range. To interact with channels, one must wrap or interact directly with the peripheral as opposed to the previous interaction with the Rednet API.
 
+
Here is a list of functions available from modems:
+
 
+
  
 
<table style="width: 100%; border: solid 1px black; margin: 2px; border-spacing: 0px;">
 
<table style="width: 100%; border: solid 1px black; margin: 2px; border-spacing: 0px;">
Line 39: Line 36:
 
==Sending Messages==
 
==Sending Messages==
 
Sending messages is simple and does not require that you open any channels. Simply use the transmit function like so:
 
Sending messages is simple and does not require that you open any channels. Simply use the transmit function like so:
  <span>
+
local modem = peripheral.wrap("right") --Wraps the modem on the right side.
  local modem = peripheral.wrap("right") --Wraps the modem on the right side.
+
modem.transmit(3, 1, "Hello world!")   
  modem.transmit(3, 1, "Hello world!")   
+
peripheral.call("right", "transmit", 3, 1, "This will also work!")
  peripheral.call("right", "transmit", 3, 1, "This will also work!")
+
  </span>
+
  
 
What did that do? First I wrapped the peripheral in order to interact with it. Second, I used modem.transmit(channel, replyChannel, message) in order to send my message. In case you were wondering, the reply channel is captured by the listening computer and suggests which channel they should reply on.
 
What did that do? First I wrapped the peripheral in order to interact with it. Second, I used modem.transmit(channel, replyChannel, message) in order to send my message. In case you were wondering, the reply channel is captured by the listening computer and suggests which channel they should reply on.
  
 
==Receiving Messages==
 
==Receiving Messages==
Receiving messages requires that you be familiar with events. As of this moment, there is no api which cuts out events from the process. Here is an example of how to receive messages:
+
Receiving messages requires that you be familiar with events. As of this moment, there is no API which cuts out events from the process. Here is an example of how to receive messages:
  <span>
+
local modem = peripheral.wrap("left")
  local modem = peripheral.wrap("left")
+
modem.open(3)--Open channel 3 so that we can listen on it
  modem.open(3)--Open channel 3 so that we can listen on it
+
local event, modemSide, senderChannel,  
  local event, modemSide, senderChannel,  
+
  replyChannel, message, senderDistance = os.pullEvent("modem_message")
    replyChannel, message, senderDistance = os.pullEvent("modem_message")
+
print("I just received a message from: "..senderChannel)
  print("I just received a message from: "..senderChannel)
+
print("I should apparently reply on: "..replyChannel)
  print("I should apparently reply on: "..replyChannel)
+
print("The modem receiving this is located on the "..modemSide.." side")
  print("The modem receiving this is located on the "..modemSide.." side")
+
print("The message was: "..message)
  print("The message was: "..message)
+
print("The sender is: "..senderDistance.." blocks away from me.")
  print("The sender is: "..senderDistance.." blocks away from me.")
+
 
  </span>
+
 
So what did I do? Quite simply, I called os.pullEvent() with the string argument "modem_message", which blocks all other events from being returned. When the "modem_message" event is captured, it returns the arguments: event, modemSide, senderChannel, replyChannel, message, senderDistance. I captured these and then printed them out.
 
So what did I do? Quite simply, I called os.pullEvent() with the string argument "modem_message", which blocks all other events from being returned. When the "modem_message" event is captured, it returns the arguments: event, modemSide, senderChannel, replyChannel, message, senderDistance. I captured these and then printed them out.
  
==Keep in Mind...==
+
== Modem Limitations ==
 
* You can only open 128 channels at any given time.
 
* You can only open 128 channels at any given time.
* The max channel you can open is 65535.
+
* The maximum channel you can open is 65535.
* You can listen on more than one channel at a time. For example, if I have channel 3 and channel 5 open and somebody sends a message on channel 5, I will still receive it. If they send a message on channel 3, I will receive that.
+
* You can listen on more than one channel at a time. For example, if the modem has channel 3 and channel 5 open, and somebody sends a message on channel 5, the modem will receive it. If a message is sent on channel 3, the modem will also receive the message.
 
* Sending messages does not require you to open any channels prior to sending it.
 
* Sending messages does not require you to open any channels prior to sending it.
* If you aren't receiving a message when you think you should, check to make sure that you have opened the channel first!
+
* If you aren't receiving a message when you think you should, check to make sure that you have opened the channel first.
* Modems and channels are not secure! If you are sending a message over rednet, it is available to any computer listening on the sent channel.
+
* Modems and channels are not secure - if you are sending a message using the Rednet API, messages are still available to any computer listening on the sent channel.
  
  
 
[[Category:Peripheral APIs]]
 
[[Category:Peripheral APIs]]

Revision as of 09:11, 6 June 2013

This page needs some serious TLC, stat!
Please help us by cleaning it, fixing it up, or sparing it some love.
(Reason: Need to add pages for missing functions --Cranium 17:13, 10 May 2013 (MSK))
This page is for the modem API. For the blocks, see Modem.

With the advent of ComputerCraft 1.5, the behavior of modems has changed somewhat drastically. Although the Rednet API still has the same functionality, it is really just a wrapper for what is a completely different system underneath.

The major change introduced to modems in this version of ComputerCraft is channels - channels are essentially networks which can be opened, closed and listened on by any computer within range. To interact with channels, one must wrap or interact directly with the peripheral as opposed to the previous interaction with the Rednet API.

Grid disk.png   Modem (API)

Method NameDescription
modem.isOpen(int channel) Checks to see if channel is open
modem.open(int channel) Opens channel to allow for listening. The channel specified must be larger than 0 and less than 65535
modem.close(int channel) Closes an open channel to disallow listening
modem.closeAll() Closes all open channels
modem.transmit(int channel, int replyChannel, string message) Transmits a message on the specified channel
modem.isWireless() Returns true if the modem is wireless; false if it is wired

Sending Messages

Sending messages is simple and does not require that you open any channels. Simply use the transmit function like so:

local modem = peripheral.wrap("right") --Wraps the modem on the right side.
modem.transmit(3, 1, "Hello world!")  
peripheral.call("right", "transmit", 3, 1, "This will also work!")

What did that do? First I wrapped the peripheral in order to interact with it. Second, I used modem.transmit(channel, replyChannel, message) in order to send my message. In case you were wondering, the reply channel is captured by the listening computer and suggests which channel they should reply on.

Receiving Messages

Receiving messages requires that you be familiar with events. As of this moment, there is no API which cuts out events from the process. Here is an example of how to receive messages:

local modem = peripheral.wrap("left")
modem.open(3)--Open channel 3 so that we can listen on it
local event, modemSide, senderChannel, 
  replyChannel, message, senderDistance = os.pullEvent("modem_message")
print("I just received a message from: "..senderChannel)
print("I should apparently reply on: "..replyChannel)
print("The modem receiving this is located on the "..modemSide.." side")
print("The message was: "..message)
print("The sender is: "..senderDistance.." blocks away from me.")

So what did I do? Quite simply, I called os.pullEvent() with the string argument "modem_message", which blocks all other events from being returned. When the "modem_message" event is captured, it returns the arguments: event, modemSide, senderChannel, replyChannel, message, senderDistance. I captured these and then printed them out.

Modem Limitations

  • You can only open 128 channels at any given time.
  • The maximum channel you can open is 65535.
  • You can listen on more than one channel at a time. For example, if the modem has channel 3 and channel 5 open, and somebody sends a message on channel 5, the modem will receive it. If a message is sent on channel 3, the modem will also receive the message.
  • Sending messages does not require you to open any channels prior to sending it.
  • If you aren't receiving a message when you think you should, check to make sure that you have opened the channel first.
  • Modems and channels are not secure - if you are sending a message using the Rednet API, messages are still available to any computer listening on the sent channel.