com.cloudpos.extboard

Interface ExtBoardDevice

All Superinterfaces:

Device

public interface ExtBoardDevice
extends Device

Interface for controlling an external board device, providing functions such as pulse triggering, relay control, digital input reading, voltage setting, and firmware version retrieval.

An instance of ExtBoardDevice is obtained as follows:

 ExtBoardDevice extBoardDevice = (ExtBoardDevice) POSTerminal.getInstance().getDevice("com.cloudpos.device.extboard");
 

The identifier "com.cloudpos.device.extboard" is used to specify the extboard device in the specific implementation.

Applications must request permission to access the extboard device:

 <uses-permission android:name="android.permission.CLOUDPOS_SERIAL"/> 

 <uses-permission android:name="android.permission.CLOUDPOS_INNER_GPIO"/> 

 <uses-permission android:name="android.permission.CLOUDPOS_VIRTUAL_SERIAL_PORT"/> 

See Also:

Device

Method Summary

Modifier and Type	Method and Description
void	cancelRead() Cancels any ongoing read operation.
int	getBoardVersion() Retrieves the firmware version of the MCU adapter board.
void	listenForRead(int length, OperationListener listener, int timeout) Asynchronously reads data from the external board.
int	readDIN(int dinPort) Reads the current logic level from the specified Digital Input (DIN) port.
void	setPulseVoltage(int voltage) Sets the output voltage level for the pulse signal.
void	triggerPulse(int portNum, int voltage, int duration, int interval, int num) Triggers a series of pulses on the specified pulse port.
void	triggerRelay(int relayPort, int relayDuration, int relayInterval, int relayCnt) Triggers the relay with specified timing parameters.
ExtBoardOperationResult	waitForRead(int length, int timeout) Synchronously reads data from the external board.
void	write(byte[] data, int length) Writes a specified number of bytes to the external board.

Methods inherited from interface com.cloudpos.Device

cancelRequest, close, getFailCount, getUsageCount, open

Method Detail

cancelRead

void cancelRead()
         throws DeviceException

Cancels any ongoing read operation. If a read is in progress, it will be interrupted.

Throws:

DeviceException - for standard errors as documented in DeviceException.

getBoardVersion

int getBoardVersion()
             throws DeviceException

Retrieves the firmware version of the MCU adapter board.

Returns:

An integer representing the board's firmware version.

Throws:

DeviceException - if an error occurs while retrieving the board version.

listenForRead

void listenForRead(int length,
                   OperationListener listener,
                   int timeout)
            throws DeviceException

Asynchronously reads data from the external board.

This method attempts to read up to the length of the provided data buffer and stores the received bytes into the buffer. The actual number of bytes read can be obtained from the result object passed to the listener.

Upon successful completion, the received data is available via ExtBoardOperationResult.getData().

This method supports a timeout mechanism. The device must respond to Device.cancelRequest() to allow cancellation of the operation in case of a timeout.

If a timeout occurs, the buffer in the operation result will contain any data received before the timeout. The operation result code will be set to OperationResult.ERR_TIMEOUT, even if partial data was received. Use ExtBoardOperationResult.getDataLength() to determine the actual number of bytes read.

The timeout parameter specifies the maximum time to wait for data, in milliseconds:

• If timeout == {@link TimeConstants#FOREVER}, the method waits indefinitely until at least one byte is available.
• If timeout == {@link TimeConstants#IMMEDIATE}, the method returns immediately with whatever data is currently available (possibly zero bytes).

Parameters:

length - The number of bytes to read.

listener - The OperationListener to be notified upon completion, timeout, or error.

timeout - The maximum time to wait for the read operation to complete, in milliseconds. Use TimeConstants.FOREVER to block indefinitely, or TimeConstants.IMMEDIATE for non-blocking read.

Throws:

DeviceException - for standard errors as documented in DeviceException.

See Also:

OperationListener.handleResult(com.cloudpos.OperationResult), ExtBoardOperationResult, TimeConstants.FOREVER, TimeConstants.IMMEDIATE

readDIN

int readDIN(int dinPort)
     throws DeviceException

Reads the current logic level from the specified Digital Input (DIN) port.

Parameters:

dinPort - The DIN port number to read from. Valid values are 0 and 1, corresponding to the two digital input channels.

Returns:

The logic level read from the DIN port. The valid return values are 0 (low) or 1 (high).

Throws:

DeviceException - if an error occurs while reading the DIN port.

setPulseVoltage

void setPulseVoltage(int voltage)
              throws DeviceException

Sets the output voltage level for the pulse signal.

Parameters:

voltage - The voltage level to set. 0 for low level, 1 for high level.

Throws:

DeviceException - if an error occurs while setting the pulse voltage.

triggerPulse

void triggerPulse(int portNum,
                  int voltage,
                  int duration,
                  int interval,
                  int num)
           throws DeviceException

Triggers a series of pulses on the specified pulse port.

Parameters:

portNum - The pulse port number to trigger. Valid values are 0 and 1, corresponding to the two pulse channels.

voltage - The voltage level of the pulse. 0 for low level, 1 for high level.

duration - The duration of each pulse in milliseconds.

interval - The interval between consecutive pulses in milliseconds.

num - The number of pulses to generate.

Throws:

DeviceException - if an error occurs while triggering the pulse.

triggerRelay

void triggerRelay(int relayPort,
                  int relayDuration,
                  int relayInterval,
                  int relayCnt)
           throws DeviceException

Triggers the relay with specified timing parameters.

Parameters:

relayPort - The relay port number to control. Currently only 0 is supported, representing the single relay channel.

relayDuration - The duration for which the relay stays active (closed) in milliseconds.

relayInterval - The interval between consecutive relay activations in milliseconds.

relayCnt - The number of times the relay should be activated.

Throws:

DeviceException - if an error occurs while triggering the relay.

waitForRead

ExtBoardOperationResult waitForRead(int length,
                                    int timeout)
                             throws DeviceException

Synchronously reads data from the external board.

This is the synchronous counterpart of listenForRead(int, OperationListener, int). It blocks until data is received, the timeout expires, or an error occurs, then returns a result object containing the read data.

The method attempts to fill the internal buffer up to the length specified by the data array passed during the request setup, but the actual number of bytes read may be less.

The timeout parameter defines the maximum waiting time in milliseconds:

• If timeout == {@link TimeConstants#FOREVER}, the method will wait indefinitely until data becomes available.
• If timeout == {@link TimeConstants#IMMEDIATE}, the method performs a non-blocking read and returns immediately.

Note that the timeout period starts when the read request begins processing, so the actual wait time may vary slightly.

Parameters:

length - The number of bytes to read.

timeout - The maximum time to wait for data, in milliseconds. Special values include TimeConstants.FOREVER and TimeConstants.IMMEDIATE.

Returns:

An ExtBoardOperationResult object containing the operation result, including the received data, the number of bytes actually read, and the operation status code.

Throws:

DeviceException - for standard errors as documented in DeviceException.

See Also:

ExtBoardOperationResult, TimeConstants.FOREVER, TimeConstants.IMMEDIATE

write

void write(byte[] data,
           int length)
    throws DeviceException

Writes a specified number of bytes to the external board.

This method is synchronous and will block until all requested bytes are written or an error occurs.

It writes length bytes from the given byte array data to the output of the external board.

Parameters:

data - The byte array containing the data to be written. Must not be null.

length - The number of bytes to write from the data array. Must be non-negative and no greater than the array length.

Throws:

DeviceException - for standard errors as documented in DeviceException.