GBDK 2020 Docs 4.4.0 API Documentation for GBDK 2020

Macros | Functions | Variables
laptop_io.h File Reference
`#include <gbdk/platform.h>`
`#include <stdint.h>`
`#include <stdbool.h>`

Go to the source code of this file.

## Macros
#define | _MEGADUCK_LAPTOP_IO_H
#define | DUCK_IO_CMD_INIT_START 0x00u
#define | DUCK_IO_CMD_GET_KEYS 0x00u
#define | DUCK_IO_CMD_DONE_OR_OK 0x01u
#define | DUCK_IO_CMD_ABORT_OR_FAIL 0x04u
#define | DUCK_IO_CMD_PLAY_SPEECH 0x05u
#define | DUCK_IO_CMD_RUN_CART_IN_SLOT 0x08u
#define | DUCK_IO_CMD_PRINT_INIT_MAYBE_EXT_IO 0x09u
#define | DUCK_IO_CMD_SET_RTC 0x0Bu
#define | DUCK_IO_CMD_GET_RTC 0x0Cu
#define | DUCK_IO_CMD_PRINT_SEND_BYTES 0x11u
#define | DUCK_IO_REPLY_BOOT_UNSET 0x00u
#define | DUCK_IO_REPLY_BOOT_FAIL 0x01u
#define | DUCK_IO_REPLY_BUFFER_XFER_OK 0x01u
#define | DUCK_IO_REPLY_SEND_BUFFER_OK 0x03u
#define | DUCK_IO_REPLY_BOOT_OK 0x01u
#define | DUCK_IO_LEN_KBD_GET 2u
#define | DUCK_IO_LEN_RTC_GET 8u
#define | DUCK_IO_LEN_RTC_SET 8u
#define | DUCK_IO_LEN_PLAY_SPEECH 1u
#define | DUCK_IO_REPLY_NO_CART_IN_SLOT 06u
#define | DUCK_IO_LEN_RX_MAX 14u
#define | DUCK_IO_LEN_TX_MAX 14u
#define | DUCK_IO_TIMEOUT_2_MSEC 2u
#define | DUCK_IO_TIMEOUT_100_MSEC 100u
#define | DUCK_IO_TIMEOUT_200_MSEC 200u
#define | DUCK_IO_SPEECH_CMD_MIN 1
#define | DUCK_IO_SPEECH_CMD_MAX 6
#define | DUCK_IO_RTC_YEAR 0u
#define | DUCK_IO_RTC_MON 1u
#define | DUCK_IO_RTC_DAY 2u
#define | DUCK_IO_RTC_WEEKDAY 3u
#define | DUCK_IO_RTC_AMPM 4u
#define | DUCK_IO_RTC_HOUR 5u
#define | DUCK_IO_RTC_MIN 6u
#define | DUCK_IO_RTC_SEC 7u
#define | DUCK_IO_KBD_FLAGS 0u
#define | DUCK_IO_KBD_KEYCODE 1u
#define | DUCK_IO_PRINTER_INIT_MASK 0x01u
#define | DUCK_IO_PRINTER_INIT_OK 0x01u
#define | DUCK_IO_PRINTER_INIT_FAIL 0x00u
#define | DUCK_IO_PRINTER_TYPE_MASK 0x02u
#define | DUCK_IO_PRINTER_TYPE_2_PASS 0x00u
#define | DUCK_IO_PRINTER_TYPE_1_PASS 0x02u

## Functions
void | duck_io_send_byte (uint8_t tx_byte)
uint8_t | duck_io_read_byte_no_timeout (void)
void | duck_io_enable_read_byte (void)
bool | duck_io_laptop_init (void)
bool | duck_io_printer_detected (void)
uint8_t | duck_io_printer_type (void)
bool | duck_io_read_byte_with_msecs_timeout (uint8_t timeout_len_ms)
bool | duck_io_send_byte_and_check_ack_msecs_timeout (uint8_t tx_byte, uint8_t timeout_len_ms, uint8_t expected_reply)
bool | duck_io_send_cmd_and_buffer (uint8_t io_cmd)
bool | duck_io_send_cmd_and_receive_buffer (uint8_t io_cmd)

## Variables
volatile bool | duck_io_rx_byte_done
volatile uint8_t | duck_io_rx_byte
uint8_t | duck_io_rx_buf [DUCK_IO_LEN_RX_MAX]
uint8_t | duck_io_rx_buf_len
uint8_t | duck_io_tx_buf [DUCK_IO_LEN_TX_MAX]
uint8_t | duck_io_tx_buf_len

## Detailed Description

# MegaDuck Laptop Peripheral IO support

The MegaDuck Laptop models (Spanish and German) have several built-in hardware peripherals which are attached via a controller that is communicated with using the serial link port.

Note
  Using the duck_io_* functions referenced from this header file will cause the duck_io_ serial interrupt handler to be automatically installed.

To use any functions here, duck_io_laptop_init() must be called first (just once).

For the present time all of the serial operations are blocking, they do not return until completed.

## Macro Definition Documentation

## ◆ _MEGADUCK_LAPTOP_IO_H

#define _MEGADUCK_LAPTOP_IO_H

## ◆ DUCK_IO_CMD_INIT_START

#define DUCK_IO_CMD_INIT_START 0x00u

Command to request starting the hardware init counter sequence process

## ◆ DUCK_IO_CMD_GET_KEYS

#define DUCK_IO_CMD_GET_KEYS 0x00u

Command to get hardware keyboard data by receiving a multi-byte packet

## ◆ DUCK_IO_CMD_DONE_OR_OK

#define DUCK_IO_CMD_DONE_OR_OK 0x01u

## ◆ DUCK_IO_CMD_ABORT_OR_FAIL

#define DUCK_IO_CMD_ABORT_OR_FAIL 0x04u

## ◆ DUCK_IO_CMD_PLAY_SPEECH

#define DUCK_IO_CMD_PLAY_SPEECH 0x05u

## ◆ DUCK_IO_CMD_RUN_CART_IN_SLOT

#define DUCK_IO_CMD_RUN_CART_IN_SLOT 0x08u

## ◆ DUCK_IO_CMD_PRINT_INIT_MAYBE_EXT_IO

#define DUCK_IO_CMD_PRINT_INIT_MAYBE_EXT_IO 0x09u

Command to init the printer and return status + model type

## ◆ DUCK_IO_CMD_SET_RTC

#define DUCK_IO_CMD_SET_RTC 0x0Bu

Command to set hardware RTC by sending a multi-byte packet

## ◆ DUCK_IO_CMD_GET_RTC

#define DUCK_IO_CMD_GET_RTC 0x0Cu

Command to get hardware RTC by receiving a a multi-byte packet

## ◆ DUCK_IO_CMD_PRINT_SEND_BYTES

#define DUCK_IO_CMD_PRINT_SEND_BYTES 0x11u

Send printer data

## ◆ DUCK_IO_REPLY_BOOT_UNSET

#define DUCK_IO_REPLY_BOOT_UNSET 0x00u

## ◆ DUCK_IO_REPLY_BOOT_FAIL

#define DUCK_IO_REPLY_BOOT_FAIL 0x01u

## ◆ DUCK_IO_REPLY_BUFFER_XFER_OK

#define DUCK_IO_REPLY_BUFFER_XFER_OK 0x01u

## ◆ DUCK_IO_REPLY_SEND_BUFFER_OK

#define DUCK_IO_REPLY_SEND_BUFFER_OK 0x03u

## ◆ DUCK_IO_REPLY_BOOT_OK

#define DUCK_IO_REPLY_BOOT_OK 0x01u

## ◆ DUCK_IO_LEN_KBD_GET

#define DUCK_IO_LEN_KBD_GET 2u

Get Keyboard key payload size: 2 bytes Payload (excludes 1 length header byte, 1 byte Checksum)

## ◆ DUCK_IO_LEN_RTC_GET

#define DUCK_IO_LEN_RTC_GET 8u

Get RTC payload size: 8 bytes Payload (excludes 1 length header byte, 1 byte Checksum)

## ◆ DUCK_IO_LEN_RTC_SET

#define DUCK_IO_LEN_RTC_SET 8u

Set RTC payload size: 8 bytes Payload (excludes 1 length header byte, 1 byte Checksum)

## ◆ DUCK_IO_LEN_PLAY_SPEECH

#define DUCK_IO_LEN_PLAY_SPEECH 1u

Play Speech payload size: 1 byte Payload (excludes 1 length header byte, 1 byte Checksum)

## ◆ DUCK_IO_REPLY_NO_CART_IN_SLOT

#define DUCK_IO_REPLY_NO_CART_IN_SLOT 06u

## ◆ DUCK_IO_LEN_RX_MAX

#define DUCK_IO_LEN_RX_MAX 14u

## ◆ DUCK_IO_LEN_TX_MAX

#define DUCK_IO_LEN_TX_MAX 14u

## ◆ DUCK_IO_TIMEOUT_2_MSEC

#define DUCK_IO_TIMEOUT_2_MSEC 2u

## ◆ DUCK_IO_TIMEOUT_100_MSEC

#define DUCK_IO_TIMEOUT_100_MSEC 100u

## ◆ DUCK_IO_TIMEOUT_200_MSEC

#define DUCK_IO_TIMEOUT_200_MSEC 200u

## ◆ DUCK_IO_SPEECH_CMD_MIN

#define DUCK_IO_SPEECH_CMD_MIN 1

## ◆ DUCK_IO_SPEECH_CMD_MAX

#define DUCK_IO_SPEECH_CMD_MAX 6

## ◆ DUCK_IO_RTC_YEAR

#define DUCK_IO_RTC_YEAR 0u

## ◆ DUCK_IO_RTC_MON

#define DUCK_IO_RTC_MON 1u

## ◆ DUCK_IO_RTC_DAY

#define DUCK_IO_RTC_DAY 2u

## ◆ DUCK_IO_RTC_WEEKDAY

#define DUCK_IO_RTC_WEEKDAY 3u

## ◆ DUCK_IO_RTC_AMPM

#define DUCK_IO_RTC_AMPM 4u

## ◆ DUCK_IO_RTC_HOUR

#define DUCK_IO_RTC_HOUR 5u

## ◆ DUCK_IO_RTC_MIN

#define DUCK_IO_RTC_MIN 6u

## ◆ DUCK_IO_RTC_SEC

#define DUCK_IO_RTC_SEC 7u

## ◆ DUCK_IO_KBD_FLAGS

#define DUCK_IO_KBD_FLAGS 0u

## ◆ DUCK_IO_KBD_KEYCODE

#define DUCK_IO_KBD_KEYCODE 1u

## ◆ DUCK_IO_PRINTER_INIT_MASK

#define DUCK_IO_PRINTER_INIT_MASK 0x01u

## ◆ DUCK_IO_PRINTER_INIT_OK

#define DUCK_IO_PRINTER_INIT_OK 0x01u

## ◆ DUCK_IO_PRINTER_INIT_FAIL

#define DUCK_IO_PRINTER_INIT_FAIL 0x00u

## ◆ DUCK_IO_PRINTER_TYPE_MASK

#define DUCK_IO_PRINTER_TYPE_MASK 0x02u

## ◆ DUCK_IO_PRINTER_TYPE_2_PASS

#define DUCK_IO_PRINTER_TYPE_2_PASS 0x00u

## ◆ DUCK_IO_PRINTER_TYPE_1_PASS

#define DUCK_IO_PRINTER_TYPE_1_PASS 0x02u

## Function Documentation

## ◆ duck_io_send_byte()

void duck_io_send_byte | ( | uint8_t | tx_byte | ) |

Sends a byte over serial to the MegaDuck laptop peripheral

Parameters

  tx_byte | Byte to send

## ◆ duck_io_read_byte_no_timeout()

uint8_t duck_io_read_byte_no_timeout | ( | void |  | ) |

Reads a byte over serial from the MegaDuck laptop peripheral with NO timeout

Returns: the received byte

If there is no reply then it will hang forever

## ◆ duck_io_enable_read_byte()

void duck_io_enable_read_byte | ( | void |  | ) |

Prepares to receive serial data from the MegaDuck laptop peripheral

- Sets serial IO to external clock and enables ready state.
- Turns on Serial interrupt, clears any pending interrupts and then turns interrupts on (state of IE_REG should be preserved before calling this and then restored at the end of the serial communication being performed).

## ◆ duck_io_laptop_init()

bool duck_io_laptop_init | ( | void |  | ) |

Performs init sequence over serial with the MegaDuck laptop peripheral

Returns `true` if successful, otherwise `false`

Needs to be done just once any time system is powered on or a cartridge is booted.

Sends count up sequence + some commands, then waits for a matching count down sequence in reverse.

## ◆ duck_io_printer_detected()

bool duck_io_printer_detected | ( | void |  | ) |

Returns whether the MegaDuck Printer was detected during duck_io_laptop_init()

Returns `true` if successful, otherwise `false`

duck_io_laptop_init() must be called first

## ◆ duck_io_printer_type()

uint8_t duck_io_printer_type | ( | void |  | ) |

Returns which type of MegaDuck Printer was detected during duck_io_laptop_init()

Return value should be one of the following:

- DUCK_IO_PRINTER_TYPE_1_PASS (single pass monochrome)
- DUCK_IO_PRINTER_TYPE_2_PASS (two pass possibly supports shades of grey)

duck_io_laptop_init() must be called first

## ◆ duck_io_read_byte_with_msecs_timeout()

bool duck_io_read_byte_with_msecs_timeout | ( | uint8_t | timeout_len_ms | ) |

Waits to receive a byte over serial from the MegaDuck laptop peripheral with a timeout

Parameters

  timeout_len_ms | Unit size is in msec (100 is about ~ 103 msec or 6.14 frames)

Returns:

- `true`: Success, received byte will be in `duck_io_rx_byte` global
- `false`: Read timed out with no reply

## ◆ duck_io_send_byte_and_check_ack_msecs_timeout()

bool duck_io_send_byte_and_check_ack_msecs_timeout | ( | uint8_t | tx_byte,
|  | uint8_t | timeout_len_ms,
|  | uint8_t | expected_reply
| ) |  |

Sends a byte over over serial to the MegaDuck laptop peripheral and waits for a reply with a timeout

Parameters

  tx_byte | Byte to send
  timeout_len_ms | Unit size is in msec (100 is about ~ 103 msec or 6.14 frames)
  expected_reply | The expected value of the reply byte

Returns:

- `true`: Success
- `false`: if timed out or reply byte didn't match expected value

## ◆ duck_io_send_cmd_and_buffer()

bool duck_io_send_cmd_and_buffer | ( | uint8_t | io_cmd | ) |

Sends a command and a multi-byte buffer over serial to the MegaDuck laptop peripheral

Parameters

  io_cmd | Command byte to send

The data should be pre-loaded into these globals:

- duck_io_tx_buf : Buffer with data to send
- duck_io_tx_buf_len : Number of bytes to send

Returns: `true` if succeeded

See also
  DUCK_IO_CMD_GET_KEYS, DUCK_IO_CMD_SET_RTC

## ◆ duck_io_send_cmd_and_receive_buffer()

bool duck_io_send_cmd_and_receive_buffer | ( | uint8_t | io_cmd | ) |

Sends a command and then receives a multi-byte buffer over serial from the MegaDuck laptop peripheral

Parameters

  io_cmd | Command byte to send

If successful, the received data and length will be in these globals:

- duck_io_rx_buf : Buffer with received data
- duck_io_rx_buf_len : Number of bytes received

Returns: `true` if succeeded, `false` if failed (could be no reply, failed checksum, etc)

See also
  DUCK_IO_CMD_GET_RTC

## Variable Documentation

## ◆ duck_io_rx_byte_done

volatile bool duck_io_rx_byte_done
| extern

## ◆ duck_io_rx_byte

volatile uint8_t duck_io_rx_byte
| extern

## ◆ duck_io_rx_buf

uint8_t duck_io_rx_buf[DUCK_IO_LEN_RX_MAX]
| extern

## ◆ duck_io_rx_buf_len

uint8_t duck_io_rx_buf_len
| extern

## ◆ duck_io_tx_buf

uint8_t duck_io_tx_buf[DUCK_IO_LEN_TX_MAX]
| extern

## ◆ duck_io_tx_buf_len

uint8_t duck_io_tx_buf_len
| extern