Command Queueing in ProGlove Connect

When setting screens, triggering feedback sequences or performing any other action on MARK, the ProGlove Connect app queues the commands it will send to the Device.

This means, that if you call for example setScreen 3 times in quick succession, these 3 screens will be displayed one after the other. As we know this behaviour is maybe not desirable, you have the possibility to cancel all the commands currently waiting in the queue and place the next command as the first to be executed next.

The behavior can be best described by sequence diagrams:

• Cx: A command triggered either via sdk or Intent
• Rx: A response (error or result object) to the command Cx.
• RCx: A command with the replace-queue flag active
• ERx: An error response to command Cx

This queue is currently limited to 5 commands. So, if a command is triggered and there are already 5 commands waiting in the queue, the response will be immediate and indicate a full queue. If the newest (6th) command has the replace queue flag enabled, it will actually not be rejected, but the queue will be cleared and the 6th command is the new head of the queue.

Intent

When using Intents, every command is sent to ProGlove Connect via an Intent. In order to trigger the command with the replace Queue flag, just add a Boolean valued extra com.proglove.api.extra.REPLACE_QUEUE to the Intent:

An example to trigger a feedback immediately, cancelling all waiting commands, could look like this:

val intent = Intent()
intent.setAction("com.proglove.api.PLAY_FEEDBACK")
intent.putExtra("com.proglove.api.extra.FEEDBACK_SEQUENCE_ID", 1)
intent.putExtra("com.proglove.api.extra.REPLACE_QUEUE", true)
sendBroadcast(intent)

Be prepared to see errors in the logs for commands which got cancelled by the above mentioned replace-queue flag.

SDK

When using the SDK, every command is sent to ProGlove Connect via a PgCommand object, which holds the necessary data for the command and can hold a PgCommandParams object. This PgCommandParams object in turn holds the data relevant for how this command should be processed insie the ProGlove Connect application.

In order to trigger the command with the replace Queue flag, just add a PgCommandParams object with replaceQueue set to true to the PgCommand. This can be done using the constructor of PgCommand or the convenience function .toCommand() of the data object for the command.

Be prepared to handle the error called CANCELED_BY_COMMAND_QUEUE_REPLACE, which will be called back for all commands which got cancelled while waiting for execution in the queue.

An example to trigger a feedback immediately, cancelling all waiting commands, could look like this:

val feedbackId = PgPredefinedFeedback.SPECIAL_1
 pgManager.triggerFeedback(feedbackId.toCommand(PgCommandParams(true)), object : IPgFeedbackCallback {
    override fun onSuccess() {
    // everything worked
    }

    override fun onError(error: PgError) {
    // handle the error
    }
})

or this:

val feedbackId = PgPredefinedFeedback.SPECIAL_1
 pgManager.triggerFeedback(PgCommand(feedbackId, PgCommandParams(true)), object : IPgFeedbackCallback {
    override fun onSuccess() {
    // everything worked
    }

    override fun onError(error: PgError) {
    // handle the error
    }
})