Docs For Class Kit108

$canonicalOutput = false

[line 230]

Public. Whether to drop the first zero from hex output.

If true, the methods which query the device's status do not prepend a zero for values lower than 0F, if the result is hexadecimal. If false, a two-character string is returned unconditionally. If $decimalOutput is set, the result of all query methods is a PHP integer regardless of this property.

Tags:

see:	Kit108::$decimalOutput
see:	Kit108::makeCanonical()

Type:

boolean

[ Top ]

$decimalOutput = false

[line 241]

Public. Whether to return output as decimal or hexadecimal.

If true, the methods which query the device's status return results in base 10 (the default is base 16).

Tags:

see:

Kit108::makeCanonical()

Type:

boolean

[ Top ]

$dev = NULL

[line 73]

Private. The current serial device (e.g. "/dev/ttyS0").

You should set this using setDev().

Tags:

see:

Kit108::Kit108()

Type:

string

[ Top ]

$errors = array()

[line 92]

Private. An array storing this object's error messages.

Tags:

see:	Kit108::addError()
see:	Kit108::getErrors()

Type:

array

[ Top ]

$forceOutEOL = ""

[line 173]

Public. Force the End Of Line character(s) used by the class.

Used by getErrors(). If not set, $outEOL is used.

Tags:

see:	Kit108::$outEOL
see:	Kit108::Kit108()
see:	Kit108::getErrors()

Type:

string

[ Top ]

$healthy = true

[line 84]

Private. This object's health status.

True if this object is healthy (see isHealthy() for what "healthy" means in this context), or false if not healthy.

For all intents and purposes, this is overridden by $neverWork.

Type:

boolean

[ Top ]

$kitEOL = "\r\n"

[line 141]

Public. The End Of Line character(s) used by the device.

Typically "\r\n" (CR/LF), set as such by default. Used by rawWrite(). Its value should be changed if the device's behavior changes in the future.

Tags:

see:

Kit108::$kitPrompt

Type:

string

[ Top ]

$kitPrompt = "#"

[line 152]

Public. The prompter provided by the device.

Typically "#", this is used to validate the device's output. Its value should be changed if the device's behavior changes in the future. The EOL before the prompt MUST NOT be included.

Tags:

see:	Kit108::$kitEOL
see:	Kit108::getKitPrompt()

Type:

string

[ Top ]

$lastOrder = ''

[line 185]

Private. The previous known order.

This is where the previous order sent through this object is stored in order to validate or clean up the device output.

Tags:

see:	Kit108::sendOrder()
see:	Kit108::read()

Type:

string

[ Top ]

$lastOrderType = NULL

[line 215]

Private. The previous known order's type.

This property remembers whether the last order was a command or a query -- used by sendOrder() to clean up the output.

Legitimate values:

NULL: no previous (known) order
"command": the previous order was a command ('N','F','T','R')
"query": the previous order was a query ('S','I','?')

Type:

set

[ Top ]

$neverWork = false

[line 200]

Private. Whether this class can possibly work in this system's context.

This is set true when there's no chance this class will ever possibly work.

For all intents and purposes, this overrides $healthy.

Tags:

see:	Kit108::$healthy
see:	Kit108::_everWork()
see:	Kit108::isHealthy()

Type:

boolean

[ Top ]

$outEOL = "\n"

[line 163]

Private. The End Of Line character(s) used by the class.

Used by getErrors(), identified by _setOutEOL() and overridden by $forceOutEOL.

Tags:

see:	Kit108::$forceOutEOL
see:	Kit108::Kit108()
see:	Kit108::getErrors()

Type:

string

[ Top ]

$serial = NULL

[line 129]

Private. The actual serial object.

Tags:

see:

Kit108::initSerial()

Type:

object

[ Top ]

$serialClassName = 'phpSerial'

[line 122]

Public. The name of the serial class.

See initSerial() for more details.

Tags:

see:	Kit108::loadDependencies()
see:	Kit108::$serialIncludeFull
see:	Kit108::$serialIncludePath

Type:

string

[ Top ]

$serialIncludeFull = ''

[line 102]

Public. The file which contains the serial class.

See initSerial() for more details.

Tags:

see:	Kit108::loadDependencies()
see:	Kit108::$serialClassName
see:	Kit108::$serialIncludePath

Type:

string

[ Top ]

$serialIncludePath = ''

[line 112]

Public. The path to the serial class file.

See initSerial() for more details.

Tags:

see:	Kit108::loadDependencies()
see:	Kit108::$serialClassName
see:	Kit108::$serialIncludeFull

Type:

string

[ Top ]

$_virgin = true

[line 252]

Private. Whether this object has ever been initialised.

This is set by setDev() the first time it's called.

Tags:

see:

Kit108::Kit108()

Type:

boolean

[ Top ]

constructor Kit108 [line 293]

boolean Kit108(
[string
$dev = NULL])

Class constructor.

If $dev is set, it calls setDev(); otherwise it does nothing. You might want it to do nothing if you want to set properties used by setDev() and other downstream methods before really initialising the object.

Tags:

return:

true on success, false on failure (as if)

Parameters:

string

$dev

[ Top ]

method addError [line 693]

void addError(
string
$error)

Public. Add an error message to this object's queue.

Retrieve errors stored this way using getErrors().

You typically shouldn't need to call this method unless you decide to use this object's error management system to store your own errors related to this device.

Parameters:

string

$error

the error message

[ Top ]

method closeDev [line 380]

boolean closeDev(
)

Public. Close the serial port.

The opposite of setDev(), this method closes the connection to the current serial device.

Tags:

return:

true on success or false on failure

[ Top ]

method getDev [line 402]

string getDev(
)

Public. Returns the current serial port.

You can set the current serial port using setDev().

Tags:

return:

the current device

[ Top ]

method getErrors [line 267]

string getErrors(
)

Public. Retrieve the current errors.

This method returns this object's current errors, in a format ready for output in the current context.

Tags:

see:	Kit108::_setOutEOL()
see:	Kit108::addError()
see:	Kit108::$forceOutEOL
see:	Kit108::$outEOL

[ Top ]

method getInput [line 1023]

integer|boolean getInput(
integer
$input)

Public. Get the status of the specified input.

The inputs are counted from zero -- that is, the first input is 0 and the last one is 3.

Tags:

return:

1 if the input is on, 0 if it is off, or boolean false on error

Parameters:

integer

$input

the input to retrieve the status of

[ Top ]

method getInputs [line 1044]

string|integer|boolean getInputs(
)

Public. Get the status of all inputs at once.

Returns a value between 0 and 15 representing the status of all device inputs (each bit represents an input; 1 means the input is set, 0 means it's not set), or boolean false on error.

The result of this method is affected by $canonicalOutput and decimalOutput.

Tags:

return:

the status of the inputs or false on error.

[ Top ]

method getKitPrompt [line 277]

string getKitPrompt(
)

Private. The prompt used by the device.

Tags:

see:

Kit108::$kitPrompt

[ Top ]

method getRelay [line 907]

integer|boolean getRelay(
integer
$relay)

Public. Returns the current state of the specified relay.

The relays are counted starting from zero (i.e. in order to get the status for the first relay you pass 0, and for the last one you pass 7).

Tags:

return:

integer 0 if the relay is not set, integer 1 if it is set, or boolean false on error

Parameters:

integer

$relay

the relay to get the status for

[ Top ]

method getRelays [line 892]

integer|string|boolean getRelays(
)

Public. Get the status for all relays at once.

Returns the status for all relays at once as a byte.

This method's result is affected by $decimalOutput and $canonicalOutput.

Each bit in the result represents a relay (the least significant bit represents the first relay, the most significant bit represents the last relay). A bit set to 1 means the relay is activated, a bit set to 0 means that it isn't.

Tags:

return:

the current status of the relays, or false on error.

[ Top ]

method getSoftwareVersion [line 487]

string|boolean getSoftwareVersion(
)

Public. Returns the Kit108 device's firmware version.

The value it returns is the version alone (e.g. "2.1"). If you want the full reply from the device, call sendOrder("?") instead.

The result is boolean false on error.

Tags:

return:

the firmware version

[ Top ]

method initDev [line 422]

boolean initDev(
[string
$dev = NULL])

Private. Initializes the current serial port for use with a Kit108 device.

This method initializes the serial devices and verifies if it can properly handshake with a Kit108 device.

If the optional $dev parameter is passed, a call to setDev() is made before actually initializing the device.

You can close the connection initialized by this method using closeDev().

Tags:

return:

true on success or false on failure

Parameters:

string

$dev

the serial device to initialize

[ Top ]

method initSerial [line 638]

boolean initSerial(
)

Private. Initialises the serial port.

This is called automatically by initDev(), you really shouldn't ever need to call it directly.

This class uses the phpSerial class to connect to the serial port in order to communicate with the device. Depending on your setup, you might want to tell this class where phpSerial resides (see $serialIncludePath and $serialIncludeFull), and what it's called (maybe you needed to rename the phpSerial class for some reason -- see $serialClassName).

Tags:

return:	true on success or false on failure
see:	Kit108::loadDependencies()

[ Top ]

method isHealthy [line 716]

boolean isHealthy(
)

Public. Checks whether this object is healthy.

Use this method at any point to find whether this object is ready to receive commands for the device -- it takes care of all implications.

This method is also used internally to determine whether to try communicating with the device -- if the object is not healthy, no communication with the device is ever attempted.

Tags:

return:	true if healthy, false otherwise
see:	Kit108::_everWork()
see:	Kit108::$neverWork
see:	Kit108::$healthy

[ Top ]

method loadDependencies [line 779]

boolean loadDependencies(
)

Private. Loads dependencies required for this class to operate.

This method behaves as follows:

If neither $serialIncludeFull nor $serialIncludePath are set, it assumes the file in which the serial class resides is named "php_serial.class.php" and is located in the same directory as this file.
If $serialIncludeFull is not set and $serialIncludePath is set, it assumes the file in which the serial class resides is named "php_serial.class.php" and is located in the directory specified in $serialIncludePath.
If $serialIncludeFull is set, it assumes the file in which the serial class resides is the file specified in $serialIncludeFull.

Tags:

return:	true on success or false on failure
see:	Kit108::initDev()

[ Top ]

method makeCanonical [line 862]

void makeCanonical(
string|boolean
$result)

Private. Formats device output according to $decimalOutput and canonicalOutput.

Parameters:

string|boolean

$result

result input data

[ Top ]

method mapInput [line 1060]

integer|boolean mapInput(
integer
$input)

Private. Map incoming input-related queries over the device native inputs.

Used by getInput(), this method shifts the input parameter by one unit and checks whether the result is valid in the device's input space.

Tags:

return:

the input number to be sent to the device for querying, or false if the input was out of bounds

Parameters:

integer

$input

the zero-based input number

[ Top ]

method mapRelay [line 1078]

void mapRelay(
mixed
$relay)

Private. Map incoming relay-related commands over the device native relays.

Used by getRelay(), toggleRelay(), relayOn(), relayOff(), setRelay(), unsetRelay().

[ Top ]

method rawRead [line 604]

string|boolean rawRead(
)

Public. This is the lowest-level method for reading from the device within the context of this class.

See rawWrite() for more context on this method.

Please note that legitimate output can be an empty string (e.g. if you call the method twice in a row) -- make sure to use the identity operator (===) to check for errors.

Tags:

return:

the output from the device on success or boolean false on failure

[ Top ]

method rawWrite [line 576]

boolean rawWrite(
string
$order)

Public. This is the lowest-level method for writing to the device within the context of this class.

In most circumstances you probably want to use sendOrder() instead of this method. Another alternative is the read()/write() combination.

Use this method in tandem with rawRead() if you want to handle all input and output from the device manually. The only pieces of logic these methods implement are the following:

The class sanity is verified before any attempt to communicate with the device (i.e. the methods will not blindly attempt to communicate if the serial device hasn't been defined or successfully initialised);
Method rawWrite() appends $kitEOL at the end of the command so you don't have to append it every time.

Apart from those, you're on your own -- you have to process device echo, prompts, the whole deal.

Tags:

return:

true on success or false on failure

Parameters:

string

$order

the order to send to the device

[ Top ]

method read [line 532]

string|boolean read(
)

Public. Read data from the device.

See write() for more context on this method.

Tags:

return:

the data read from the device or boolean false on failure

[ Top ]

method relayOff [line 958]

boolean relayOff(
integer
$relay)

Public. Deactivate the specified relay.

The relays are counted starting from zero (see getRelay()).

Tags:

return:

true on success or false on failure

Parameters:

integer

$relay

the relay to deactivate

[ Top ]

method relayOn [line 941]

boolean relayOn(
integer
$relay)

Public. Activate the specified relay.

The relays are counted starting from zero (see getRelay()).

Tags:

return:

true on success or false on failure

Parameters:

integer

$relay

the relay to activate

[ Top ]

method sendOrder [line 1108]

string|boolean sendOrder(
string
$order)

Public. Send an order to the device and retrieve the output.

This is the highest-level method in the context of this class except the truly dedicated methods like setRelays(), getRelays(), etc.

This method uses write() and rawRead() to handle all I/O strings related to a Kit108 unit -- it processes the EOLs, the device prompt, echo and so on; it interprets the type of command it has been issued in the context of a Kit108 unit (it decides whether it was given a command or it was asked to provide the result of a query) and acts accordingly.

Tags:

return:

the device's response in case of a query, boolean true if a command has been successfully passed to the device, or boolean false on failure

Parameters:

string

$order

the order for the device

[ Top ]

method setAllRelays [line 996]

boolean setAllRelays(
)

Public. Activate all relays.

Identical to setRelays(255).

Tags:

return:

true on success or false on failure

[ Top ]

method setDev [line 349]

boolean setDev(
string
$dev)

Public. Sets the current object's serial device and initializes it.

This method is also called by the class constructor, if the device parameter is passed to the constructor.

The first time this method is called, it calls _setOutEOL() and _everWork() (and sets $_virgin in order to register that is has been called once).

This method always sets $healthy by calling initDev().

You can retrieve the current device with getDev().

Tags:

return:

true on success, false on failure. The return value is also populated in $healthy.

Parameters:

string

$dev

the device to use

[ Top ]

method setHexRelays [line 832]

boolean setHexRelays(
$relays
$relays)

Public. Sets all relays to the hexadecimal value passed in $relays.

Identical in every way to setRelays(), except this method takes the input in hexadecimal.

Tags:

return:

true on succes or false on failure

Parameters:

$relays

$relays

string a hexadecimal byte which indicates the values for all relays

[ Top ]

method setRelay [line 973]

boolean setRelay(
integer
$relay)

Public. Alias for relayOn().

Tags:

return:

true on success or false on failure

Parameters:

integer

$relay

the relay to activate

[ Top ]

method setRelays [line 811]

boolean setRelays(
integer
$relays)

Public. Sets all relays to the values passed in $relays.

The device has eight relays, and there are eight bits in a byte. This method takes a value between 0 and 255 and sets all eight relays according to on and off depending on whether the bits in the input value are set (relay ON) or not set (relay OFF).

Passing values below 0 or above 255 will result in an error.

Tags:

return:

true on succes or false on failure

Parameters:

integer

$relays

a byte which indicates the values for all relays

[ Top ]

method testDev [line 470]

boolean testDev(
)

Public. Test the current device.

Assumes the current device is set up already and tests whether it works properly. This is automatically called by initDev(), it doesn't need to be called by your code at the beginning of the session.

Tags:

return:

true if the device responded properly or false otherwise.

[ Top ]

method toggleRelay [line 924]

boolean toggleRelay(
integer
$relay)

Public. Toggle the status of the specified relay.

The relays are counted starting from zero (see getRelay()).

Tags:

return:

true on success or false on failure

Parameters:

integer

$relay

the relay to toggle

[ Top ]

method unsetAllRelays [line 1008]

boolean unsetAllRelays(
)

Public. Deactivate all relays.

Identical to setRelays(0).

Tags:

return:

true on success or false on failure

[ Top ]

method unsetRelay [line 984]

boolean unsetRelay(
integer
$relay)

Public. Alias for relayOff().

Tags:

return:

true on success or false on failure

Parameters:

integer

$relay

the relay to deactivate

[ Top ]

method write [line 515]

boolean write(
string
$order)

Public. Write data to the device.

Both read() and write() are relatively low-level methods within the context of this class, you typically don't need to call them directly. In most contexts, you probably want to call sendOrder() instead.

On the other hand, these methods still perform some logic of their own within the context of this class, and read() attempts to clean up the output. If you want to go down and dirty and process all I/O manually, use rawRead() and rawWrite() instead.

As opposed to sendOrder(), this method only writes the order to the serial device, without waiting for or processing the output -- you will need to call read() afterwards to retrieve the output.

Tags:

return:

true on success, false on failure

Parameters:

string

$order

the order to send

[ Top ]

method _everWork [line 740]

boolean _everWork(
)

Private. Decides whether this class will ever work on this system.

This is where $neverWork is set (or not). The decision is based on the operating system you're using. Currently only Linux is fully supported. You can override the default behavior by setting constant KIT108_OVERRIDE_OS to boolean true (strict). For more details, see this page.

Tags:

return:	true if it may, false if it may not work here
see:	Kit108::isHealthy()
see:	Kit108::$neverWork
see:	Kit108::$healthy

[ Top ]

method _setOutEOL [line 315]

boolean _setOutEOL(
)

Private. Decides a default EOL for output depending on the context.

This method sets $outEOL depending on the following factors:

If the code is being executed in the context of an HTTP request, the EOL is unconditionally "
\n".
If the code is being executed under Linux, the default "\n" is retained.
Otherwise, "\r\n" (CR/LF) is used.

The defaults can be overridden by $forceOutEOL.

Tags:

return:

true unconditionally

[ Top ]

Class: Kit108

Class Overview

Variables

Methods

Class Details

Class Variables

$canonicalOutput = false

Tags:

$decimalOutput = false

Tags:

$dev = NULL

Tags:

$errors = array()

Tags:

$forceOutEOL = ""

Tags:

$healthy = true

$kitEOL = "\r\n"

Tags:

$kitPrompt = "#"

Tags:

$lastOrder = ''

Tags:

$lastOrderType = NULL

$neverWork = false

Tags:

$outEOL = "\n"

Tags:

$serial = NULL

Tags:

$serialClassName = 'phpSerial'

Tags:

$serialIncludeFull = ''

Tags:

$serialIncludePath = ''

Tags:

$_virgin = true

Tags:

Class Methods

constructor Kit108 [line 293]

Tags:

Parameters:

method addError [line 693]

Parameters:

method closeDev [line 380]

Tags:

method getDev [line 402]

Tags:

method getErrors [line 267]

Tags:

method getInput [line 1023]

Tags:

Parameters:

method getInputs [line 1044]

Tags:

method getKitPrompt [line 277]

Tags:

method getRelay [line 907]

Tags:

Parameters:

method getRelays [line 892]

Tags:

method getSoftwareVersion [line 487]

Tags:

method initDev [line 422]

Tags:

Parameters:

method initSerial [line 638]

Tags:

method isHealthy [line 716]

Tags:

method loadDependencies [line 779]

Tags:

method makeCanonical [line 862]

Parameters:

method mapInput [line 1060]

Tags:

Parameters:

method mapRelay [line 1078]

method rawRead [line 604]