Difference between revisions of "Redstone (API)"

From ComputerCraft Wiki
Jump to: navigation, search
(Updated to API overview v2)
m
 
(20 intermediate revisions by 8 users not shown)
Line 1: Line 1:
The Redstone API contains methods to control attached RedPower cables/bundled cables and regular redstone.
+
The Redstone API contains methods to control attached redstone. All methods from the redstone API can also be called using "rs", which points to the same library. For example, instead of redstone.getSides(), rs.getSides() can be used.
 +
 
 +
In addition to regular redstone / RedPower cables for regular signals, [[Redstone_(API)#Bundled_Cables|bundled cables]] may be used to send/receive "combined" signals through the one face. The [[Colors (API)|Colors API]] offers functions that're helpful information in dealing with these.
  
 
<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 10: Line 12:
  
 
<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[redstone.getSides]]()</td>
 
<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[redstone.getSides]]()</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns an array of possible sides</td></tr>
+
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns a table of possible sides.</td></tr>
  
<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[redstone.getInput]]([[string (type)|string]] side)</td>
+
<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[redstone.getInput]]({{type|string}} side)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns the current redstone input signal state on ''side''</td></tr>
+
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns the current redstone input signal state on ''side''.</td></tr>
  
<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[redstone.setOutput]]([[string (type)|string]] side, [[boolean (type)|boolean]] value)</td>
+
<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[redstone.setOutput]]({{type|string}} side, {{type|boolean}} value)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Set or reset a redstone signal on ''side''</td></tr>
+
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Sets or resets a redstone signal on ''side''.</td></tr>
  
<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[redstone.getOutput]]([[string (type)|string]] side)</td>
+
<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[redstone.getOutput]]({{type|string}} side)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns the current redstone output signal on ''side''</td></tr>
+
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns the current redstone output signal on ''side''.</td></tr>
  
<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[redstone.getBundledInput]]([[string (type)|string]] side)</td>
+
<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[redstone.getAnalogInput]]({{type|string}} side)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns the state of a redpower wire inside a bundle connected to ''side''</td></tr>
+
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">'''(Requires CC1.51 and above)''' Returns the current redstone input signal strength on ''side''. If no input is present, returns 0. If a redstone source (such as a redstone torch or block) is directly adjacent to the computer, returns 15.</td></tr>
  
<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[redstone.getBundledOutput]]([[string (type)|string]] side)</td>
+
<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[redstone.setAnalogOutput]]({{type|string}} side, {{type|number}} strength)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns the set of redpower wires inside a bundle on ''side'' that are being driven high <b>by the local console</b> (not those that are driven high by another device on the bundle but not driven high by the local console)</td></tr>
+
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">'''(Requires CC1.51 and above)''' Sets or resets a redstone signal on ''side'' to ''strength'' (where ''strength'' is a positive integer).</td></tr>
  
<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[redstone.setBundledOutput]]([[string (type)|string]] side, [[int (type)|int]] colors)</td>
+
<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[redstone.getAnalogOutput]]({{type|string}} side)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Sets one or multiple colored signals in a redpower bundled wire connected to ''Side''. In order to set multiple signals, add the color values of the colors you want to activate. To turn off all of the values, use 0 for the integer.</td></tr>
+
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">'''(Requires CC1.51 and above)''' Returns the current redstone output signal strength on ''side''.</td></tr>
  
<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[redstone.testBundledInput]]([[string (type)|string]] side, [[int (type)|int]] color)</td>
+
<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[redstone.getBundledInput]]({{type|string}} side)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns true or false whether or not a colored signal is active in a redpower bundled wire connected to ''Side''</td></tr>
+
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns the state (as a number) of a [[Redstone_(API)#Bundled_Cables|bundled cable]] connected to ''side''.</td></tr>
 +
 
 +
<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[redstone.getBundledOutput]]({{type|string}} side)</td>
 +
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns the set of wires in a [[Redstone_(API)#Bundled_Cables|bundled cable]] which are being activated by the terminal on ''side''.</td></tr>
 +
 
 +
<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[redstone.setBundledOutput]]({{type|string}} side, {{type|number}} colors)</td>
 +
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Sets one or multiple colored signals in a [[Redstone_(API)#Bundled_Cables|bundled cable]] attached to ''side''. ''colors'' will determine which signals are activated. In order to set multiple signals, [[colors.combine|add the color values of the colors]] you want to activate. To turn off all of the colors, use 0.</td></tr>
 +
 
 +
<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[redstone.testBundledInput]]({{type|string}} side, {{type|number}} color)</td>
 +
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns true if ''color'' is active in a [[Redstone_(API)#Bundled_Cables|bundled cable]] attached to ''side''. Else, returns false.</td></tr>
  
 
</table>
 
</table>
  
 +
:{|class="wikitable"
 +
| ''[[Usage_of_the_bundled_cable_using_the_Redstone_API|Bundled cable code snippet. (You might want to take a look at this if you are doing bundledcable related things.)]]''
 +
|}
 +
 +
== Data exchange ==
 +
The redstone API can be used to exchange data between adjacent [[computer]]s and [[turtle]]s. Four bits of data can be transmitted and received with each use of redstone signals to send analog output and receive the input. One redstone signal can be sent at each tick [https://minecraft.gamepedia.com/Tick tick], and there are 20 ticks per second in Minecraft. This limits data transmission over redstone to a maximum of 80 bits per second (bps).
 +
 +
This makes large-scale data transmission over the redstone API exceedingly slow. For example, using the redstone API, transmitting a colored bitmap image for a maximum [[resolution]] computercraft monitor cluster (162x80 pixels) would require 10 minutes and 48 seconds (this would be a 6.48 kB image). For reference, there are 16 colors available for monitors and terminals in computercraft, so a single color for a pixel can be represented in a 4-bit signal.
 +
 +
Despite the slowness, the redstone API can be useful when other options are not available. For example, it can be used to allow [[turtle]]s to communicate with each other and coordinate their work even if they do not have [[Wireless Modem]]s. Exchanging instructions can be done with much less total data than exchanges of image files and the like.
 +
 +
==Bundled Cables==
 +
 +
A "bundled cable" contains multiple wires, one for each of the basic 16 dye colors present in Minecraft. Each acts as a redstone dust line, allowing multiple redstone signals to pass through a space without interfering with each other. They are extremely handy for building complex control mechanisms, and can be dealt with using the [[redstone.getBundledInput|rs.getBundledInput]], [[redstone.getBundledOutput|rs.getBundledOutput]], [[redstone.setBundledOutput|rs.setBundledOutput]] and [[redstone.testBundledInput|rs.testBundledInput]] functions.
 +
 +
ComputerCraft itself does not offer any form of bundled cable - rather, such 16-wire leads are provided by other mods, and they aren't always specifically called "bundled cables", either. Compatibility has changed over time.
 +
 +
ComputerCraft 1.1 (for Minecraft 1.0) through to 1.5 (for MC 1.4.7) users have access to [http://ftbwiki.org/Bundled_Cable bundled cables], provided by [http://www.eloraam.com RedPower/RedPower 2].
 +
 +
1.51 (for MC 1.5) through to 1.58 (for MC 1.6.4) users can switch to [http://ftbwiki.org/RedNet_Cable RedNet cables] (nothing to do with [[Rednet_(API)|ComputerCraft's Rednet]]!) from [http://www.minecraftforum.net/forums/mapping-and-modding/minecraft-mods/1292152-powercrystals-mods-minefactoryreloaded#mfr MineFactory Reloaded].
 +
 +
1.6 introduced an API allowing other mod authors to code support into their mods, while at the same time dropping in-built support for RedNet cables. No known leads are compatible with ComputerCraft 1.6 to 1.63 (for MC 1.6.4) - stick to 1.58 and its RedNet cable compatibility if you wish to use them under that build of Minecraft.
 +
 +
Under 1.64 through to the present 1.74 (all for MC 1.7.10), a number of cables are now available - [http://projectredwiki.com/wiki/Bundled_Cable bundled cables] from [http://projectredwiki.com/wiki/Main_Page Project Red], [http://wiki.enderio.com/Insulated_Redstone_Conduit Insulated Redstone Conduits] from [http://wiki.enderio.com/Main_Page Ender IO], and it's believed current versions of MineFactory Reloaded also work again via their RedNet cables. Others may be available too, so experiment with what you've got, and remember to try updating your mods if you're having trouble!
 +
 +
Mod authors wishing to make their cables compatible can inspect api/doc/index.html, within the ComputerCraft mod archive, for details.
  
 
[[Category:APIs]]
 
[[Category:APIs]]

Latest revision as of 07:04, 4 August 2020

The Redstone API contains methods to control attached redstone. All methods from the redstone API can also be called using "rs", which points to the same library. For example, instead of redstone.getSides(), rs.getSides() can be used.

In addition to regular redstone / RedPower cables for regular signals, bundled cables may be used to send/receive "combined" signals through the one face. The Colors API offers functions that're helpful information in dealing with these.

Grid disk.png   Redstone (API)

Method NameDescription
redstone.getSides() Returns a table of possible sides.
redstone.getInput(string side) Returns the current redstone input signal state on side.
redstone.setOutput(string side, boolean value) Sets or resets a redstone signal on side.
redstone.getOutput(string side) Returns the current redstone output signal on side.
redstone.getAnalogInput(string side) (Requires CC1.51 and above) Returns the current redstone input signal strength on side. If no input is present, returns 0. If a redstone source (such as a redstone torch or block) is directly adjacent to the computer, returns 15.
redstone.setAnalogOutput(string side, number strength) (Requires CC1.51 and above) Sets or resets a redstone signal on side to strength (where strength is a positive integer).
redstone.getAnalogOutput(string side) (Requires CC1.51 and above) Returns the current redstone output signal strength on side.
redstone.getBundledInput(string side) Returns the state (as a number) of a bundled cable connected to side.
redstone.getBundledOutput(string side) Returns the set of wires in a bundled cable which are being activated by the terminal on side.
redstone.setBundledOutput(string side, number colors) Sets one or multiple colored signals in a bundled cable attached to side. colors will determine which signals are activated. In order to set multiple signals, add the color values of the colors you want to activate. To turn off all of the colors, use 0.
redstone.testBundledInput(string side, number color) Returns true if color is active in a bundled cable attached to side. Else, returns false.
Bundled cable code snippet. (You might want to take a look at this if you are doing bundledcable related things.)

Data exchange

The redstone API can be used to exchange data between adjacent computers and turtles. Four bits of data can be transmitted and received with each use of redstone signals to send analog output and receive the input. One redstone signal can be sent at each tick tick, and there are 20 ticks per second in Minecraft. This limits data transmission over redstone to a maximum of 80 bits per second (bps).

This makes large-scale data transmission over the redstone API exceedingly slow. For example, using the redstone API, transmitting a colored bitmap image for a maximum resolution computercraft monitor cluster (162x80 pixels) would require 10 minutes and 48 seconds (this would be a 6.48 kB image). For reference, there are 16 colors available for monitors and terminals in computercraft, so a single color for a pixel can be represented in a 4-bit signal.

Despite the slowness, the redstone API can be useful when other options are not available. For example, it can be used to allow turtles to communicate with each other and coordinate their work even if they do not have Wireless Modems. Exchanging instructions can be done with much less total data than exchanges of image files and the like.

Bundled Cables

A "bundled cable" contains multiple wires, one for each of the basic 16 dye colors present in Minecraft. Each acts as a redstone dust line, allowing multiple redstone signals to pass through a space without interfering with each other. They are extremely handy for building complex control mechanisms, and can be dealt with using the rs.getBundledInput, rs.getBundledOutput, rs.setBundledOutput and rs.testBundledInput functions.

ComputerCraft itself does not offer any form of bundled cable - rather, such 16-wire leads are provided by other mods, and they aren't always specifically called "bundled cables", either. Compatibility has changed over time.

ComputerCraft 1.1 (for Minecraft 1.0) through to 1.5 (for MC 1.4.7) users have access to bundled cables, provided by RedPower/RedPower 2.

1.51 (for MC 1.5) through to 1.58 (for MC 1.6.4) users can switch to RedNet cables (nothing to do with ComputerCraft's Rednet!) from MineFactory Reloaded.

1.6 introduced an API allowing other mod authors to code support into their mods, while at the same time dropping in-built support for RedNet cables. No known leads are compatible with ComputerCraft 1.6 to 1.63 (for MC 1.6.4) - stick to 1.58 and its RedNet cable compatibility if you wish to use them under that build of Minecraft.

Under 1.64 through to the present 1.74 (all for MC 1.7.10), a number of cables are now available - bundled cables from Project Red, Insulated Redstone Conduits from Ender IO, and it's believed current versions of MineFactory Reloaded also work again via their RedNet cables. Others may be available too, so experiment with what you've got, and remember to try updating your mods if you're having trouble!

Mod authors wishing to make their cables compatible can inspect api/doc/index.html, within the ComputerCraft mod archive, for details.