Functions

LibMK_Controller *libmk_create_controller(LibMK_Handle *handle)

Create a new LibMK_Controller for a defined handle.

After initialization of the Controller, the Handle may no longer be used directly. The lifecycle of the created controller is the responsibility of the user.

LibMK_Result libmk_free_controller(LibMK_Controller *c)

Free a LibMK_Controller.

First performs a check to see if the controller is still active. An active controller may not be freed. Returns LIBMK_ERR_STILL_ACTIVE if the controller is still active.

int libmk_sched_instruction(LibMK_Controller *controller, LibMK_Instruction *instruction)

Schedule a linked-list of instructions.

Instruction scheduler than schedules the given linked-list of instructions at the end of the list of the controller in the given order. After scheduling, all instructions are given an ID number and they may not be scheduled again. After execution, the instructions are freed and thus after scheduling an instruction may not be accessed again.

Returns the instruction ID of the first instruction in the linked list (it is the user’s responsibility to derive the ID number of the other instructions) upon success (postive integer) or a LibMK_Result (negative integer) upon failure.

LibMK_Result libmk_cancel_instruction(LibMK_Controller *c, unsigned int id)

Cancel a scheduled instruction by its ID number.

If the instruction has already been executed, the instruction is not cancelled and the function fails quietly. Does not cancel any successive instructions even if the instruction was scheduled as part of a linked-list.

LibMK_Result libmk_start_controller(LibMK_Controller *controller)

Start a new Controller thread.

Start the execution of instructions upon the keyboard in a different thread. This function enables control of the keyboard and initializes the thread.

void libmk_run_controller(LibMK_Controller *controller)

Internal Function. Execute Controller instructions.

void libmk_stop_controller(LibMK_Controller *controller)

Request an exit on a running controller.

The request is passed using the exit_flag, and thus the Controller may not immediately be stopped. To assure that the controller has stopped, use libmk_join_controller.

void libmk_wait_controller(LibMK_Controller *controller)

Indicate the controller to finish only pending instructions.

If instructions are scheduled in the mean-time, they are added to the linked list and still executed by the Controller before exiting. Only after the linked list has become empty does the Controller exit.

This function sets the wait_flag, and thus the Controller has not necessarily stopped after this function ends. To assure that the Controller has stopped, use libmk_join_controller.

LibMK_Controller_State libmk_join_controller(LibMK_Controller *c, double t)

Join the Controller thread.

Return

LIBMK_STATE_JOIN_ERR upon timeout, controller state after exiting upon success.

Parameters
  • t: Timeout in seconds

void libmk_set_controller_error(LibMK_Controller *c, LibMK_Result r)

Internal Function.

LibMK_Instruction *libmk_create_instruction()

Allocate a new LibMK_Instruction struct.

LibMK_Instruction *libmk_create_instruction_full(unsigned char c[3])

Create a new instruction to set the full keyboard color.

Return

: Pointer to single LibMK_Instruction. Duration may be set by the caller.

Parameters
  • c: RGB color triplet that is copied to the instruction.

LibMK_Instruction *libmk_create_instruction_all(unsigned char c[LIBMK_MAX_ROWS][LIBMK_MAX_COLS][3])

Create a new instruction to set all leds individually.

Return

: Pointer to single LibMK_Instruction. Duration may be set by the caller.

Parameters
  • c: RGB color matrix that is copied to the instruction.

LibMK_Instruction *libmk_create_instruction_flash(unsigned char c[3], unsigned int delay, unsigned char n)

Create a new list of instructions to flash the keyboard.

Makes use of LIBMK_INSTR_FULL type instructions. Builds a linked list of n instructions.

Return

: Pointer to linked list of LibMK_Instruction.

Parameters
  • c: RGB color triplet that is copied to the instruction.

  • delay: Duration set for each individual instruction of the linked list in microseconds, excluding the time required for instruction execution itself.

  • n: Number of instructions in the linked list to be built.

LibMK_Instruction *libmk_create_instruction_single(unsigned char row, unsigned char column, unsigned char c[3])

: Create a new instruction to set the color of a single key

Overridden by a LIBMK_INSTR_FULL, just as in synchronous keyboard control. When changing six or more keys, using a LIBMK_INSTR_ALL is faster.

Return

: Single LibMK_Instruction, duration may be set by the user.

Parameters
  • row: Row coordinate of the key

  • column: Column coordinate of the key

  • c: RGB triplet to be copied to the instruction

void libmk_free_instruction(LibMK_Instruction *i)

: Free a single LibMK_Instruction

The instruction is expected to longer be part of a linked list. This instruction is automatically called after an instruction has been executed and should only be called by the user if an instruction must be freed before it is scheduled. Use libmk_cancel_instruction to cancel scheduled instructions, which are then freed after cancelling.

LibMK_Result libmk_exec_instruction(LibMK_Handle *h, LibMK_Instruction *i)

: Internal Function. Execute a single instruction. NOT THREAD-SAFE.