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"/>
 

Code Obfuscation Notice:
If your application uses ProGuard or R8 code shrinking and obfuscation, you MUST keep all classes in the com.cloudpos.sdk.extboard.bean package unobfuscated. These classes (MDBEvent, MDBConfig, and MDBOption) implement android.os.Parcelable and are used for inter-process communication with the CloudPOS SDK.

Add the following rule to your proguard-rules.pro file:

 -keep class com.cloudpos.sdk.extboard.bean.** { *; }
 

This package contains only these three essential Parcelable classes, so the above rule ensures they—and all their fields and methods— remain intact after obfuscation. Failure to include this rule may result in runtime crashes such as ClassNotFoundException, NoSuchFieldException, or corrupted data during MDB communication.

See Also:

Device

Method Summary

Modifier and Type	Method and Description
void	cancelPollEvent() Cancels a pending pollEvent(int) operation.
void	cancelRead() Cancels any ongoing read operation.
void	enableAutoBeginSession(int enable, float defaultFundsAmount) Enables or disables automatic session start behavior for cashless operation.
int	getBoardVersion() Retrieves the firmware version of the MCU adapter board.
MDBConfig	getConfig() Retrieves the current MDB configuration parameters from the external board.
MDBOption	getOption() Retrieves the current optional feature settings for cashless MDB operation.
void	listenForRead(int length, OperationListener listener, int timeout) Asynchronously reads data from the external board.
MDBEvent	pollEvent(int timeoutMS) Waits for an MDB event from the external board.
int	readDIN(int dinPort) Reads the current logic level from the specified Digital Input (DIN) port.
void	respondEvent(MDBEvent evtData) Sends an MDB event response to the external board.
void	setCashlessAddress(int address) Sets the cashless device address for MDB communication.
void	setConfig(MDBConfig mdbConfig) Sets the MDB configuration parameters for cashless operation.
void	setOption(MDBOption mdbOption) Sets optional feature flags for cashless MDB operation.
void	setPulseVoltage(int voltage) Sets the output voltage level for the pulse signal.
void	startLoop() Starts the internal event processing loop for the external board.
void	stopLoop() Stops the internal event processing loop.
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

cancelPollEvent

void cancelPollEvent()
              throws DeviceException

Cancels a pending pollEvent(int) operation.

If a thread is currently blocked waiting for an event in pollEvent(int), this method will interrupt the wait and cause pollEvent(int) to return with an error.

Throws:

DeviceException - if an error occurs while canceling the poll operation.

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.

enableAutoBeginSession

void enableAutoBeginSession(int enable,
                            float defaultFundsAmount)
                     throws DeviceException

Enables or disables automatic session start behavior for cashless operation.

When automatic session begin is enabled, the MDB board will automatically initiate a cashless session using the specified default funds amount, without requiring an explicit session start command from the host.

When disabled, the application is responsible for explicitly managing the cashless session lifecycle.

Parameters:

enable - Set to 1 to enable automatic session begin, or 0 to disable it.

defaultFundsAmount - The default available funds amount used when automatically starting a session.

Throws:

DeviceException - if an error occurs while configuring the automatic session begin behavior.

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.

getConfig

MDBConfig getConfig()
             throws DeviceException

Retrieves the current MDB configuration parameters from the external board.

This method reads back the actual configuration currently applied on the MDB board. The returned MDBConfig object will have its outLevel, outDecimalPlace, outScaleFactor, and outCurrencyCode fields populated with the retrieved values. The inXXX fields in the returned object are undefined and should be ignored.

Returns:

A new MDBConfig instance containing the current configuration values in its outXXX fields.

Throws:

DeviceException - if an error occurs while retrieving the configuration.

getOption

MDBOption getOption()
             throws DeviceException

Retrieves the current optional feature settings for cashless MDB operation.

This method reads back the actual option flags currently active on the MDB board. The returned MDBOption object will have its outEnableAlwaysIdle, outEnableExpandedCurrency, outEnableRemoteVend, outEnableBasketPartialRefund, and outEnableNegativeVend fields populated with the current settings (false = disabled, true = enabled). The inXXX fields in the returned object are undefined and should be ignored.

Returns:

A new MDBOption instance containing the current option settings in its outXXX fields.

Throws:

DeviceException - if an error occurs while retrieving the options.

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

pollEvent

MDBEvent pollEvent(int timeoutMS)
            throws DeviceException

Waits for an MDB event from the external board.

This method blocks until an event is received from the MDB board, the specified timeout expires, or the operation is canceled. The event data will be returned in a new MDBEvent object upon successful completion.

startLoop() must be called before invoking this method; otherwise, this method may fail or block indefinitely depending on the implementation.

The timeoutMS parameter specifies the maximum time to wait for an event:

• If timeoutMS > 0, the method waits up to the specified number of milliseconds.
• If timeoutMS == {@link TimeConstants#FOREVER}, the method waits indefinitely until an event is received.
• Negative values (other than TimeConstants.FOREVER) are treated as invalid and may result in an error.

Parameters:

timeoutMS - The maximum time to wait for an event, in milliseconds. Use TimeConstants.FOREVER to wait indefinitely.

Returns:

A new MDBEvent instance containing the received event data. The fields such as eventType, eventResult, eventAmount, etc., will be populated based on the actual event from the hardware.

Throws:

DeviceException - if an error occurs during communication, the timeout expires, the loop is not started, or the operation is canceled.

See Also:

startLoop(), cancelPollEvent(), TimeConstants.FOREVER

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.

respondEvent

void respondEvent(MDBEvent evtData)
           throws DeviceException

Sends an MDB event response to the external board.

This method transmits the specified MDBEvent to the MDB board, typically as a response to an event previously received via pollEvent(int). The response usually includes acknowledgment, result code, and optional data such as approved amount or item information.

The evtData object must be non-null and should reflect the correct response format expected by the MDB protocol (e.g., setting appropriate eventResult and eventAmount fields).

Parameters:

evtData - The MDBEvent to be sent to the MDB board as a response. Must not be null.

Throws:

DeviceException - if evtData is null, communication fails, or the device is not ready to send a response.

See Also:

MDBEvent, pollEvent(int)

setCashlessAddress

void setCashlessAddress(int address)
                 throws DeviceException

Sets the cashless device address for MDB communication.

This method configures the MDB address used by the cashless device when communicating with the MDB bus. The address must be set correctly to ensure proper communication with the vending machine controller.

Parameters:

address - The cashless device address to set. Set 1 or 2 ,default 1.

Throws:

DeviceException - if an error occurs while setting the cashless address.

setConfig

void setConfig(MDBConfig mdbConfig)
        throws DeviceException

Sets the MDB configuration parameters for cashless operation.

This method configures various parameters used in MDB communication, including value scaling, decimal formatting, and currency identification. These parameters must match the vending machine controller configuration.

The input values are taken from the mdbConfig.inLevel, mdbConfig.inDecimalPlace, mdbConfig.inScaleFactor, and mdbConfig.inCurrencyCode fields. The outXXX fields in the provided object are ignored.

Parameters:

mdbConfig - The MDBConfig object containing the configuration values to set. Must not be null.

Throws:

DeviceException - if an error occurs while setting the configuration.

setOption

void setOption(MDBOption mdbOption)
        throws DeviceException

Sets optional feature flags for cashless MDB operation.

This method enables or disables optional MDB behaviors supported by the external board and vending machine controller. Each feature is controlled by a boolean-like integer flag (false = disabled, true = enabled).

The input values are taken from the mdbOption.inEnableAlwaysIdle, mdbOption.inEnableExpandedCurrency, mdbOption.inEnableRemoteVend, mdbOption.inEnableBasketPartialRefund, and mdbOption.inEnableNegativeVend fields. The outXXX fields in the provided object are ignored.

Parameters:

mdbOption - The MDBOption object containing the option flags to set. Must not be null.

Throws:

DeviceException - if an error occurs while setting the options.

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.

startLoop

void startLoop()
        throws DeviceException

Starts the internal event processing loop for the external board.

This method enables the main loop that continuously processes communication and events from the MDB board. It must be called before invoking pollEvent(int) or receiving any asynchronous events.

Throws:

DeviceException - if an error occurs while starting the loop.

stopLoop

void stopLoop()
       throws DeviceException

Stops the internal event processing loop.

This method terminates the loop previously started by startLoop(). After calling this method, no further events will be received and any pending pollEvent(int) operation will be canceled.

Throws:

DeviceException - if an error occurs while stopping the loop.

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.