Computer Interfacing

Stargate Interface

Stargates can be monitored and controlled by computers from ComputerCraft or OpenComputers using a Stargate Interface block. There are two versions of this block, depending on which kind of computer you are using. The interface block should be placed somewhere underneath the bottom row of ring blocks.

ComputerCraft interface block placement example

Open Computers interface block placement example

Accessing the Interface

ComputerCraft	Open Computers
Use peripheral.wrap() with the appropriate side or peripheral ID, e.g. sg = peripheral.wrap("right") sg = peripheral.wrap("stargate_1")	If there is only one stargate connected to the computer, you can access it as the primary component of type "stargate": component = require("component") sg = component.getPrimary("stargate") Otherwise you will need to access it by its address, which you can find by using an Analyzer on the interface block, e.g. sg = component.proxy("6f2a9642-2ab3-482f-930f-812fadafb48e")

Methods

The stargate interface peripheral provides the following methods.

Addresses passed as arguments may be either 7 or 9 characters, with or without hyphens. Addresses returned are always 9 characters without hyphens.

stargateState()

Returns: state, engaged, direction

state is one of:

Idle	Operating and ready to dial
Dialling	In the process of dialling an address
Opening	Finished dialling, wormhole in transient phase
Connected	Wormhole is stable
Closing	Wormhole is shutting down
Offline	Interface not connected to a functioning stargate

engaged is the number of engaged chevrons

direction is one of:

Outgoing	Connection was dialled from this end
Incoming	Connection was dialled from the other end
Empty string	Not connected

energyAvailable()

Returns the amount of energy in the gate's internal buffer plus the buffers of any attached Stargate Power Units. This is the energy available for the next dialling operation. If the interface is not connected to a functioning stargate, zero is returned.

Energy is measured in stargate energy units (SU). Relationships between SU and other energy units are:

IndustrialCraft	1 SU = 20 EU
Thermal Expansion	1 SU = 80 RF

energyToDial(address)

Returns the amount of energy that would be needed to connect to the stargate at the given address.

localAddress()

Returns the address of the attached stargate. If the interface is not connected to a functioning stargate, an empty string is returned.

remoteAddress()

Returns the address of the connected stargate. If there is no connection, or the interface is not connected to a functioning stargate, an empty string is returned.

dial(address)

Dials the given address.

disconnect()

Closes any open connection.

irisState()

Returns a string indicating the state of the iris: Closed, Opening, Open, Closing. Returns Offline if no iris is fitted or the interface is not connected to a functioning stargate.

closeIris()

Closes the iris, if fitted.

openIris()

Opens the iris, if fitted.

sendMessage(arg, ...)

Sends a message through an open connection to any stargate interfaces attached to the destination stargate. Any number of arguments may be passed. The message is delivered to connected computers as an sgMessageReceived event. Has no effect if no stargate connection is open.

Error Handling

In the event of an error, methods of the stargate interface return a pair of values nil, error_message. Methods that do not otherwise return any values return true on success.

NOTE: Prior to SG Craft version 1.11, stargate methods raised an exception on error. If you were relying on that, you will now need to check the result of each interface call for errors. You may find a function like this useful for wrapping interface calls:

function check(a, b, ...)
    if a == nil then
        error(b, 0)
    end
    return a, b, ...
end

For example,

check(sg.dial(address))

Events

Stargate events have the general form

name, source, args...

where name is the name of the event, and source is the peripheral ID (ComputerCraft) or component address (Open Computers) of the interface block that the event came from.

Event	Description
sgDialIn, source, remote address	An incoming connection has been initiated
sgDialOut, source, remote address	An outgoing connection has been initiated
sgChevronEngaged, source, chevron number, symbol	A chevron has been engaged during dialling
sgStargateStateChange, source, new state, old state	State of stargate has changed
sgIrisStateChange, source, new state, old state	State of iris has changed
sgMessageReceived, source, arg, ...	A message was sent from the connected stargate using the sendMessage method

Open Computers Networking

Open Computers wireless network messages will pass through an open stargate connection. By default, the message is rebroadcast on the other side with a strength of 50; you can change this with the wirelessRebroadcastStrength configuration option.

In addition, if there is a stargate interface at each end, and both of them have a Network Card (non-wireless) installed in the upgrade slot, wired network messages will be relayed between the two interfaces. (Note that this only applies to network messages. Messages sent using the sendMessage method of the stargate interface do not require network cards.)

Example Code

Some small Lua programs exercising the functions of the interface.

Programs	Library Code
Programs	Common	ComputerCraft	Open Computers
dial disconnect energy events interactive iris state	addresses	config compat	config compat

Code as Zip File

ComputerCraft:		ccexamples.zip
Open Computers:		ocexamples.zip