Difference between revisions of "Modem (API)"

From ComputerCraft Wiki
Jump to: navigation, search
m (Merge "method" and "parameters" fields. (TODO port to API-table-type))
(Additional functions for wired modems.)
 
(27 intermediate revisions by 16 users not shown)
Line 1: Line 1:
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.
+
:''This page is for the modem API. For the blocks, see [[Modem]].''
 +
{{PeripheralAPI}}
  
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 directly wrap the peripheral as opposed to the previous interaction with the rednet API.
 
  
Here is a list of functions available from modems:
+
Available to [[peripheral.wrap|wrapped]] [[Wireless Modem|Wireless]], [[Ender Modem|Ender]], or [[Wired Modem|Wired]] Modems.
{| border="1" cellpadding="2" cellspacing="0"
+
!style="background:#EEE" width="200px"|Function
+
!style="background:#EEE" width="*"|Description
+
|-
+
|isOpen( [[int_(type)|int]] channel )
+
|Check to see if the specified channel is open
+
|-
+
|open( [[int_(type)|int]] channel )
+
|Opens the specified channel to allow for listening. The channel specified must be larger than 0 and less than 65535.
+
|-
+
|close( [[int_(type)|int]] channel )
+
|Closes an open channel to disallow listening
+
|-
+
|closeAll( )
+
|Closes all open channels
+
|-
+
|transmit( [[int_(type)|int]] channel, [[int_(type)|int]] replyChannel, [[string_(type)|string]] message )
+
|Transmits a message on the specified channel
+
|}
+
==Sending Messages==
+
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.
+
  modem.transmit(3, 1, "Hello world!") 
+
  </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.
+
Direct use of modems requires understanding of the "channels" system - these are essentially networks which can be [[modem.open|opened]], [[modem.close|closed]] and [[modem_message_(event)|listened]] on by any [[Computer]] within range, without need of independent computer IDs. To interact with channels, one must [[peripheral.wrap|wrap]] or otherwise interact directly with the peripheral. The [[Rednet_(API)|Rednet API]] acts as a wrapper for your modem's functionality, handling the channel system for you (basically by having each system listen on a channel equal to its ID number).
  
==Receiving Messages==
+
Functions in ''italics'' are only available to [[Wired Modem]]s, which are able to connect to remote peripherals and control them from afar.
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")
+
  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.")
+
  </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.
+
  
==Keep in Mind...==
+
 
* You can only open 128 channels at any given time.
+
{{API table|Modem|image=Grid disk.png|2=
* The max 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.
+
{{API table/row
 +
|[[modem.isOpen|''modem''.isOpen]]({{type|number}} channel)
 +
|{{type|boolean}} isChannelOpen
 +
|Checks to see if ''channel'' is open.
 +
|odd}}
 +
 
 +
{{API table/row
 +
|[[modem.open|''modem''.open]]({{type|number}} channel)
 +
|{{type|nil}}
 +
|Opens ''channel'' to allow for listening. The channel specified must be larger than 0 and less than 65535.}}
 +
 
 +
{{API table/row
 +
|[[modem.close|''modem''.close]]({{type|number}} channel)
 +
|{{type|nil}}
 +
|Closes an open channel to disallow listening.
 +
|odd}}
 +
 
 +
{{API table/row
 +
|[[modem.closeAll|''modem''.closeAll]]()
 +
|{{type|nil}}
 +
|Closes all open channels.}}
 +
 
 +
{{API table/row
 +
|[[modem.transmit|''modem''.transmit]]({{type|number}} channel, {{type|number}} replyChannel, {{type|any}} message)
 +
|{{type|nil}}
 +
|Transmits a message on the specified channel.
 +
|odd}}
 +
 
 +
{{API table/row
 +
|[[modem.isWireless|''modem''.isWireless]]()
 +
|{{type|boolean}} isWireless
 +
|Returns if the modem is wireless or wired.}}
 +
 
 +
{{API table/row
 +
|''[[modem.getNamesRemote|modem.getNamesRemote]]()''
 +
|{{type|table}} peripheralNames
 +
|Returns a table containing the network names of the peripherals connected to the modem.
 +
|odd}}
 +
 
 +
{{API table/row
 +
|''[[modem.getTypeRemote|modem.getTypeRemote]]({{type|string}} peripheralName)''
 +
|{{type|string}} type
 +
|Returns the type of a given peripheral connected to the modem.}}
 +
 
 +
{{API table/row
 +
|''[[modem.isPresentRemote|modem.isPresentRemote]]({{type|string}} peripheralName)''
 +
|{{type|boolean}} present
 +
|Returns whether a given peripheral is actively connected to the modem.
 +
|odd}}
 +
 
 +
{{API table/row
 +
|''[[modem.getMethodsRemote|modem.getMethodsRemote]]({{type|string}} peripheralName)''
 +
|{{type|table}} methodNames
 +
|Returns a list strings naming the functions available to the specified peripheral.}}
 +
 
 +
{{API table/row
 +
|''[[modem.callRemote|modem.callRemote]]({{type|string}} peripheralName, {{type|string}} method, ...)''
 +
|any
 +
|Has the remote peripheral execute its specified function.
 +
|odd}}
 +
 
 +
}}
 +
 
 +
{{Event
 +
|name=modem_message
 +
|return1={{type|string}} modemSide
 +
|return2={{type|number}} senderChannel
 +
|return3={{type|number}} replyChannel
 +
|return4= message
 +
|return5={{type|number}} distance
 +
|desc=Fired when a modem message is received.}}
 +
 
 +
== Sending Messages ==
 +
Sending a message 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 a message requires that you be familiar with [[os.pullEvent|events]]. An example:
 +
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 on channel: "..senderChannel)
 +
print("I should apparently reply on channel: "..replyChannel)
 +
print("The modem receiving this is located on my "..modemSide.." side")
 +
print("The message was: "..message)
 +
print("The sender is: "..(senderDistance or "an unknown number of").." 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 [[modem_message_(event)|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, per modem.
 +
* The highest 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.
 
* 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 Modem API, messages are still available to any computer listening on the sent channel. By extension, the [[rednet (API)|Rednet API]] (which handles your modems for you using their peripheral APIs) is also insecure.
 +
 
 +
 
 +
[[Category:Peripheral APIs]]

Latest revision as of 03:33, 9 January 2016

This page is for the modem API. For the blocks, see Modem.
This API requires the use of a wrapped peripheral!
This API does not behave like a regular API, to use it you must first wrap the peripheral and call the methods on the wrapped object. For more information see this page.


Available to wrapped Wireless, Ender, or Wired Modems.

Direct use of modems requires understanding of the "channels" system - these are essentially networks which can be opened, closed and listened on by any Computer within range, without need of independent computer IDs. To interact with channels, one must wrap or otherwise interact directly with the peripheral. The Rednet API acts as a wrapper for your modem's functionality, handling the channel system for you (basically by having each system listen on a channel equal to its ID number).

Functions in italics are only available to Wired Modems, which are able to connect to remote peripherals and control them from afar.


Grid disk.png  Modem (API)
Function Return values Description
modem.isOpen(number channel) boolean isChannelOpen Checks to see if channel is open.
modem.open(number channel) nil Opens channel to allow for listening. The channel specified must be larger than 0 and less than 65535.
modem.close(number channel) nil Closes an open channel to disallow listening.
modem.closeAll() nil Closes all open channels.
modem.transmit(number channel, number replyChannel, any message) nil Transmits a message on the specified channel.
modem.isWireless() boolean isWireless Returns if the modem is wireless or wired.
modem.getNamesRemote() table peripheralNames Returns a table containing the network names of the peripherals connected to the modem.
modem.getTypeRemote(string peripheralName) string type Returns the type of a given peripheral connected to the modem.
modem.isPresentRemote(string peripheralName) boolean present Returns whether a given peripheral is actively connected to the modem.
modem.getMethodsRemote(string peripheralName) table methodNames Returns a list strings naming the functions available to the specified peripheral.
modem.callRemote(string peripheralName, string method, ...) any Has the remote peripheral execute its specified function.
Grid Modem.png  Event modem_message
Fired when a modem message is received.
Returned Object 1 string modemSide
Returned Object 2 number senderChannel
Returned Object 3 number replyChannel
Returned Object 4 message
Returned Object 5 number distance


Sending Messages

Sending a message 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 a message requires that you be familiar with events. An example:

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 on channel: "..senderChannel)
print("I should apparently reply on channel: "..replyChannel)
print("The modem receiving this is located on my "..modemSide.." side")
print("The message was: "..message)
print("The sender is: "..(senderDistance or "an unknown number of").." 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, per modem.
  • The highest 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 Modem API, messages are still available to any computer listening on the sent channel. By extension, the Rednet API (which handles your modems for you using their peripheral APIs) is also insecure.