Difference between revisions of "Peripheral (API)"

From ComputerCraft Wiki
Jump to: navigation, search
(Added some continuity to the printers)
(Computers: Adding modems)
 
(32 intermediate revisions by 14 users not shown)
Line 1: Line 1:
The peripheral API is for interacting with external [http://en.wikipedia.org/wiki/Peripheral peripherals], such as the disk drive and monitor.<br />
+
{{msgbox
[[Console|Consoles]] and [[Turtle|Turtles]] are also considered peripherals and you can interface two adjacent computers, although in a more limited fashion compared to [[Rednet (API)|rednet]]. Both Computers and Turtles provide the same methods: ''turnOn'', ''shutdown'', ''reboot'', ''getID''.
+
| text = This article is about the Peripheral API. For APIs exposed when wrapping peripherals through [[peripheral.wrap]]() see [[:Category:Peripheral_APIs|Peripheral APIs]].
 +
}}
  
==Methods==
+
__TOC__
{| class="wikitable"
+
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]]).
!style="background:#EEE" width="210px"|Method name
+
!style="background:#EEE" width="*"|Description
+
|-
+
|[[peripheral.isPresent]]( side )
+
|Returns '''true''' if a peripheral is present on ''side''.
+
|-
+
|[[peripheral.getType]]( side )
+
|Returns the type or peripheral present on ''side'', nothing returned if ''side'' is empty.
+
|-
+
|[[peripheral.getMethods]]( side )
+
|Returns a table containing all methods for peripheral on ''side''.
+
|-
+
|[[peripheral.call]]( side, methodName, param1, param2, ... )
+
|Sends a function call to peripheral located on ''side''. Return values match those of called method.<br />
+
'''Note:''' ''methodName'' is a string.
+
|-
+
|[[peripheral.wrap]]( side )
+
|Returns a handle to the peripheral located on ''side''. If assigned to a variable, it can be used to call all methods available from that peripheral, as if calling '''peripheral.call()''', e.g.:<br />
+
m = [[peripheral.wrap]]("left")<br />
+
m.someMethod()<br />
+
''- is the same as -''<br />
+
[[peripheral.call]]("left","someMethod")
+
|}
+
  
==Events==
+
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.
{| class="wikitable"
+
!style="background:#EEE" width="210px"|Event name
+
!style="background:#EEE" width="*"|Description
+
!style="background:#EEE" width="*"|Parameters
+
|-
+
|peripheral
+
|Fired when peripheral is attached
+
|side
+
|-
+
|peripheral_detach
+
|Fired when peripheral is removed
+
|side
+
|}
+
==Monitor==
+
List of methods:
+
  
'''''monitor'' stands for the variable you wrapped the monitor to.'''
+
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".
''Example:'' monitor = peripheral.wrap( "top" )
+
  
{| class="wikitable"
+
Peripheral functions are called '''methods''', a term borrowed from Java.
!style="background:#EEE" width="210px"|Method name
+
!style="background:#EEE" width="*"|Description
+
|-
+
|[[term.write|''monitor''.write]]()
+
|Write to the Monitor's screen.
+
|-
+
|[[term.scroll|''monitor''.scroll]]( n )
+
|Scrolls the monitor screen.
+
|-
+
|[[term.setCursorPos|''monitor''.setCursorPos]]( x, y )
+
|Sets the cursor position on the Monitor.
+
|-
+
|[[term.setCursorBlink|''monitor''.setCursorBlink]]( b )
+
|Enables or disables cursor blinking.
+
|-
+
|[[term.getCursorPos|''monitor''.getCursorPos]]()
+
|Returns two arguments containing the x and the y position of the cursor on the Monitor.
+
|-
+
|[[term.getSize|''monitor''.getSize]]()
+
|Returns two arguments containing the x and the y values stating the size of the Monitor.
+
|-
+
|[[term.clear|''monitor''.clear]]()
+
|Clears the Monitor.
+
|-
+
|[[term.clearLine|''monitor''.clearLine]]()
+
|Clears the line the cursor is on.
+
|-
+
|''monitor''.setTextScale( scale )
+
|Sets the size of the text on the Monitor. Textscale can be between 1.0 and 5.0, with increments of 0.5
+
|}
+
==Printer==
+
List of methods:
+
  
'''''printer'' stands for the variable you wrapped the printer to.'''
+
{{API table|Peripheral|image=Grid disk.png|2=
''Example:'' printer = peripheral.wrap( "right" )
+
  
{| class="wikitable"
+
{{API table/row|[[peripheral.isPresent]]({{type|string}} side)|{{type|boolean}}|
!style="background:#EEE" width="200px"|Method name
+
Returns '''true''' if a peripheral is connected on ''side''.
!style="background:#EEE" width="*"|Description
+
|odd}}
|-
+
 
|''printer''.[[printer.newPage|newPage]]()
+
{{API table/row|[[peripheral.getType]]({{type|string}} side)|{{type|string}} /{{type|nil}}|
|Starts a new page. Returns true if page got started, false if not.
+
Returns the type of peripheral connected on ''side'', as a string.
|-
+
If no peripheral is connected, returns nil.
|''printer''.[[printer.endPage|endPage]]()
+
}}
|Ends the page and prints the page to the output tray. Returns true if page was ended, false if not.
+
 
|-
+
{{API table/row|[[peripheral.getMethods]]({{type|string}} side)|{{type|table}} /{{type|nil}}|
|''printer''.[[printer.write|write]]( text )
+
Returns a list of the names of all the methods of the peripheral connected on ''side''.
|Writes text to the paper, works the same way as [[term.write()]]
+
If no peripheral is connected, returns nil.
|-
+
|odd}}
|''printer''.[[printer.setPageTitle|setPageTitle]]( text )
+
 
|Sets the title of the page.
+
{{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.
|''printer''.[[printer.getPaperLevel|getPaperLevel]]()
+
If no peripheral is connected, returns nil.
|Returns the amount of paper available in the paper tray.
+
}}
|-
+
 
|''printer''.[[printer.getInkLevel|getInkLevel]]()
+
{{API table/row|[[peripheral.wrap]]({{type|string}} side)|{{type|table}} peripheral / {{type|nil}}|
|Returns the amount of ink in the ink slot.
+
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.
|''printer''.[[printer.getCursorPos|getCursorPos]]()
+
|odd}}
|Returns the coordinates of the cursor on the paper, works the same way as [[term.getCursorPos()]]
+
 
|-
+
{{API table/row|[[peripheral.find]]({{type|string}} type [, {{type|function}} fnFilter( name, object )])|{{type|table}} peripheral / {{type|nil}}|
|''printer''.[[printer.setCursorPos|setCursorPos]]( x, y )
+
Finds an attached peripheral of the given type and if found returns a table of functions, similar to [[peripheral.wrap]], allowing you to call peripheral methods as if they were normal Lua functions.
|Sets the cursor pos.
+
If no peripheral of the given type is connected, it returns nil. '''''Requires ComputerCraft 1.6 or later.'''''
|-
+
|odd}}
|''printer''.[[printer.getPageSize|getPageSize]]()
+
 
|Returns the size of the paper, works the same way as [[term.getSize()]]
+
{{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]] and [[Advanced Monitor]] peripheral functions can be found on the [[Term (API)]] page. Note that the [[Colors (API)|Colors API]] can also be useful for designing colors for use on an advanced monitor.
 +
 
 +
==Printer==
 +
[[Printer#Printer API |Printer Peripheral functions]] have been moved to the [[Printer]] page.
  
 
==Computers==
 
==Computers==
List of methods:
+
[[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.
  
'''''computer'' stands for the variable you wrapped the computer to.'''
+
==Modem==
''Example:'' computer = peripheral.wrap( "top" )
+
[[Modem]] peripheral functions can be found on the [[Modem (API)]] page.
  
{| class="wikitable"
 
!style="background:#EEE" width="210px"|Method name
 
!style="background:#EEE" width="*"|Description
 
|-
 
|''computer''.turnOn()
 
|Turns on the Computer or Turtle.
 
|-
 
|''computer''.shutdown()
 
|Shuts off the Computer or Turtle.
 
|-
 
|''computer''.reboot()
 
|Reboots the Computer or Turtle.
 
|-
 
|''computer''.getID()
 
|Gets the ID of the Computer or Turtle.
 
|}
 
 
[[Category:APIs]]
 
[[Category:APIs]]

Latest revision as of 04:06, 9 November 2014

This article is about the Peripheral API. For APIs exposed when wrapping peripherals through peripheral.wrap() see Peripheral APIs.

The Peripheral API is for interacting with peripherals connected to the computer, such as the Disk Drive, the Advanced Monitor and Monitor. (More peripherals can be found under 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.

Grid disk.png  Peripheral (API)
Function Return values Description
peripheral.isPresent(string side) boolean

Returns true if a peripheral is connected on side.

peripheral.getType(string side) string /nil

Returns the type of peripheral connected on side, as a string. If no peripheral is connected, returns nil.

peripheral.getMethods(string side) table /nil

Returns a list of the names of all the methods of the peripheral connected on side. If no peripheral is connected, returns nil.

peripheral.call(string side, 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.

peripheral.wrap(string side) table peripheral / 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.

peripheral.find(string type [, function fnFilter( name, object )]) table peripheral / nil

Finds an attached peripheral of the given type and if found returns a table of functions, similar to peripheral.wrap, allowing you to call peripheral methods as if they were normal Lua functions. If no peripheral of the given type is connected, it returns nil. Requires ComputerCraft 1.6 or later.

peripheral.getNames() 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.

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 and Advanced Monitor peripheral functions can be found on the Term (API) page. Note that the Colors API can also be useful for designing colors for use on an advanced monitor.

Printer

Printer Peripheral functions have been moved to the Printer page.

Computers

Computer Peripheral functions have been moved to the Computer page. In addition, the Advanced Computer Peripheral functions have been moved to the Advanced Computer page.

Modem

Modem peripheral functions can be found on the Modem (API) page.