MAGResWCHDLL |

Loading...
Searching...
No Matches
Macros | Typedefs | Enumerations | Functions
MAGResWCH.h File Reference

MAGResWCH DLL API for controlling the MAGRes board. More...

`#include <stdint.h>`

Go to the source code of this file.

## Macros
#define | MAGRESWCH_API __declspec(dllimport)

## Typedefs
typedef struct dio_handle_s * | dio_handle_h
| The board handle.
typedef struct dio_bmp_s * | dio_bmp_h
| The handle for a bmp file.

## Enumerations
enum | dio_errors_e { ERR_CANNOT_ALLOCATE_LPNMASTERHANDLE = -1 , ERR_INVALID_CH367_HANDLE = -2 , ERR_CANNOT_GET_IO_REG_ADDR = -3 , ERR_STEP_SIZE_LESS_EQUAL_ZERO = -4 , ERR_WRITE_LONGER_THAN_AVAIL_MEM = -5 , ERR_WRITE_ZERO_BYTES = -6 , ERR_READ_ZERO_BYTES = -7 , ERR_SPI_READ_ERR = -8 , ERR_SPI_STREAM_ERR = -9 , ERR_SPI_WRITE_ERR = -10 , ERR_SPI_ADDR_OUT_OF_BOUNDS = -11 , ERR_BMP_INVALID_FILE = -12 }
| Errors represented by lpnStatus. More...
enum | dio_ext_trigger_modes_e { DIO_EXT_TRIG_IGNORE = 0 , DIO_EXT_TRIG_RISING_EDGE , DIO_EXT_TRIG_FALLING_EDGE , DIO_EXT_TRIG_HIGH_HOLD , DIO_EXT_TRIG_LOW_HOLD }
| External Trigger modes. More...
enum | dio_adrsr_pin_state_e { DIO_ADRSR_PIN_LOW = 0 , DIO_ADRSR_PIN_HIGH }
enum | dio_oled_write_mode_e { DIO_OLED_MODE_OVERWRITE = 0 , DIO_OLED_MODE_OR , DIO_OLED_MODE_GREATER_THAN , DIO_OLED_MODE_XOR , DIO_OLED_MODE_NONZERO }
| Pixel blending modes when using the OLED screen buffer. More...

## Functions
MAGRESWCH_API void | DioInitialize (short nMasterNum, dio_handle_h *lpnMasterHandle, int16_t *lpnStatus)
| Provides a one time initialization of a master board and all slave boards associated with it.
MAGRESWCH_API void | DioArm (dio_handle_h nMasterHandle, int16_t *lpnStatus)
| Changes the board state from Halt to Pause.
MAGRESWCH_API void | DioHalt (dio_handle_h nMasterHandle, int16_t *lpnStatus)
| Changes specified master board state to HALT.
MAGRESWCH_API void | DioPause (dio_handle_h nMasterHandle, int16_t *lpnStatus)
| Changes the specified master board state from a RUN to PAUSE state.
MAGRESWCH_API void | DioTrig (dio_handle_h nMasterHandle, int16_t *lpnStatus)
| Takes the specified master board state from PAUSE to RUN.
MAGRESWCH_API void | DioReadCtrlMemory (dio_handle_h nHandle, uint32_t *lnpdwVector, uint32_t dwStart, uint32_t dwSize, int16_t *lpnStatus)
| Reads a block of control memory from the specified board.
MAGRESWCH_API void | DioReadOutMemory (dio_handle_h nHandle, uint32_t *lnpdwVector, uint32_t dwStart, uint32_t dwSize, int16_t *lpnStatus)
| Reads a block of output memory from the specified board.
MAGRESWCH_API void | DioWriteCtrlMemory (dio_handle_h nHandle, uint32_t *lpdwMemory, uint32_t dwStart, uint32_t dwSize, int16_t *lpnStatus)
| Writes a block of data to the control memory of the specified board.
MAGRESWCH_API void | DioWriteOutMemory (dio_handle_h nHandle, uint32_t *lpdwMemory, uint32_t dwStart, uint32_t dwSize, int16_t *lpnStatus)
| Writes a block of data to the output memory of the specified board.
MAGRESWCH_API void | DioReadProgramCounter (dio_handle_h nHandle, int32_t *lpdwCounter, int16_t *lpnStatus)
| Returns the specified master board program counter value.
MAGRESWCH_API void | DioWriteProgramCounter (dio_handle_h nHandle, int32_t dwCounter, int16_t *lpnStatus)
| Writes the specified master board program counter value.
MAGRESWCH_API void | DioReadCurrentIO (dio_handle_h nHandle, int32_t *lpdwCounter, int16_t *lpnStatus)
| Returns the specified master board current output value.
MAGRESWCH_API void | DioWriteCurrentIO (dio_handle_h nHandle, int32_t dwCounter, int16_t *lpnStatus)
| Writes the specified master board current output value.
MAGRESWCH_API void | DioReadStatusRegister (dio_handle_h nHandle, int16_t *lpwData, int16_t *lpnStatus)
| Reads the status register from the specified board.
MAGRESWCH_API void | DioReset (dio_handle_h nHandle, int16_t *lpnStatus)
| Changes state of specified master board to HALT.
MAGRESWCH_API void | DioStep (dio_handle_h nMasterHandle, int32_t dwSteps, int16_t *lpnStatus)
| Executes the specified master board program for a number of steps.
MAGRESWCH_API void | DioReadMaxDataLines (dio_handle_h nHandle, int32_t *lpdwCounter, int16_t *lpnStatus)
| Returns the specified master board max data lines available to program.
MAGRESWCH_API void | DioClearCtrlMemory (dio_handle_h nMasterHandle, int16_t *lpnStatus)
| Clears the control memory on the board.
MAGRESWCH_API void | DioClearOutMemory (dio_handle_h nMasterHandle, int16_t *lpnStatus)
| Clears the output memory on the board.
MAGRESWCH_API void | DioStreamSPI (dio_handle_h nMasterHandle, uint8_t addr, uint8_t *write_buff, uint8_t *read_buff, size_t len, int16_t *lpnStatus)
| Streams the SPI.
MAGRESWCH_API void | DioWriteSPI (dio_handle_h nMasterHandle, uint8_t addr, uint8_t *write_buff, size_t len, int16_t *lpnStatus)
| Writes to the SPI.
MAGRESWCH_API void | DioReadSPI (dio_handle_h nMasterHandle, uint8_t addr, uint8_t *read_buff, size_t len, int16_t *lpnStatus)
| Reads the SPI.
MAGRESWCH_API void | DioResetDDS (dio_handle_h nMasterHandle, int16_t *lpnStatus)
| Resets and initializes the DDS. Can only be sent during HALT.
MAGRESWCH_API void | DioSetupTriggerMode (dio_handle_h nMasterHandle, uint8_t nPauseMode, uint8_t nRunMode, int16_t *lpnstatus)
| Sets the external trigger mode during the PAUSE and RUN states.
MAGRESWCH_API void | DioClose (dio_handle_h nMasterHandle, int16_t *lpnStatus)
| Closes the connection to the board, and releases the handle from being used.
MAGRESWCH_API void | DioSetADRSR_Low (dio_handle_h nMasterHandle, uint8_t io_byte)
MAGRESWCH_API void | DioSetADRSR_High (dio_handle_h nMasterHandle, uint8_t io_byte)
MAGRESWCH_API void | DioSetupOLED (dio_handle_h nMasterHandle, int16_t *lpnStatus)
| Sets up and turns on the OLED.
MAGRESWCH_API void | DioWriteOLEDPixelPairImm (dio_handle_h nMasterHandle, uint8_t column, uint8_t y, uint8_t val)
| Writes a value to a pair of pixels immediately.
MAGRESWCH_API void | DioWriteOLEDPixelPairBuff (dio_handle_h nMasterHandle, dio_oled_write_mode_e mode, uint8_t column, uint8_t y, uint8_t val)
| Writes a value to a pair of pixels in the local screen buffer.
MAGRESWCH_API void | DioWriteOLEDPixelImm (dio_handle_h nMasterHandle, uint8_t row, uint8_t column, uint8_t val)
| Writes a pixel to the screen at the designated coordinate immediately.
MAGRESWCH_API void | DioWriteOLEDPixelBuff (dio_handle_h nMasterHandle, dio_oled_write_mode_e mode, uint8_t x, uint8_t y, uint8_t val)
| Writes a pixel to the screen at the designated coordinate in the local screen buffer.
MAGRESWCH_API void | DioWriteOLEDLineImm (dio_handle_h nMasterHandle, uint8_t x1, uint8_t y1, uint8_t x2, uint8_t y2, uint8_t val1, uint8_t val2)
| Immediately writes a line to the screen that begins at (x1, y1), with value `val1`, to (x2, y2) with value `val2`.
MAGRESWCH_API void | DioWriteOLEDLineBuff (dio_handle_h nMasterHandle, dio_oled_write_mode_e mode, uint8_t x1, uint8_t y1, uint8_t x2, uint8_t y2, uint8_t val1, uint8_t val2)
| Writes a line to the local screen buffer that begins at (x1, y1), with value `val1`, to (x2, y2) with value `val2`.
MAGRESWCH_API void | DioWriteOLEDArrImm (dio_handle_h nMasterHandle, uint8_t x, uint8_t y, uint8_t *arr, size_t len)
| Writes an array of length len to screen immediately.
MAGRESWCH_API void | DioWriteOLEDArrBuff (dio_handle_h nMasterHandle, dio_oled_write_mode_e mode, uint8_t x, uint8_t y, uint8_t *arr, size_t len)
| Writes an array of length len to the local screen buffer.
MAGRESWCH_API void | DioWriteOLEDScreenArrImm (dio_handle_h nMasterHandle, uint8_t *arr)
| Writes 128x64 bytes to the screen at once, given a single dimensional array of that size.
MAGRESWCH_API void | DioWriteOLEDScreenArrBuff (dio_handle_h nMasterHandle, dio_oled_write_mode_e mode, uint8_t *arr)
| Writes 128x64 bytes to the local screen buffer, given a single dimensional array of that size.
MAGRESWCH_API void | DioWriteOLEDRowArrImm (dio_handle_h nMasterHandle, uint8_t y, uint8_t *arr)
| Writes an array of length 128 to a row on screen immediately.
MAGRESWCH_API void | DioWriteOLEDRowArrBuff (dio_handle_h nMasterHandle, dio_oled_write_mode_e mode, uint8_t y, uint8_t *arr)
| Writes an array of length 128 to a row in the local screen buffer.
MAGRESWCH_API void | DioWriteOLEDRowValImm (dio_handle_h nMasterHandle, uint8_t y, uint8_t val)
| Writes singular value to a row on screen immediately.
MAGRESWCH_API void | DioWriteOLEDAreaArrImm (dio_handle_h nMasterHandle, uint8_t x, uint8_t y, uint8_t col_width, uint8_t height, uint8_t *arr)
| Writes an array of length `col_width*height` to the screen immediately.
MAGRESWCH_API void | DioWriteOLEDAreaArrBuff (dio_handle_h nMasterHandle, dio_oled_write_mode_e mode, uint8_t x, uint8_t y, uint8_t col_width, uint8_t height, uint8_t *arr)
| Writes an array of length `col_width*height` to the local screen buffer.
MAGRESWCH_API void | DioWriteOLED2DUnpackedArrImm (dio_handle_h nMasterHandle, uint8_t **arr)
| Writes 128x64 bytes to the screen at once, given a single dimensional array of that size.
MAGRESWCH_API void | DioSendOLEDBuff (dio_handle_h nMasterHandle)
| Sends the current local screen buffer to the OLED screen.
MAGRESWCH_API void | DioClearOLEDBuff (dio_handle_h nMasterHandle)
| Clears the current local screen buffer.
MAGRESWCH_API void | DIOClearOLEDImm (dio_handle_h nMasterHandle)
| Clears the screen immediately.
MAGRESWCH_API dio_bmp_h | DioOpenBMP (dio_handle_h nMasterHandle, char *path, int16_t *lpnStatus)
| Opens and allocates memory for a bitmap file.
MAGRESWCH_API void | DioCloseBMP (dio_handle_h nMasterHandle, dio_bmp_h *bmp_handle)
| Closes and deallocates memory for a bitmap file.
MAGRESWCH_API void | DioWriteOLEDAreaBMPImm (dio_handle_h nMasterHandle, uint8_t x, uint8_t y, dio_bmp_h bmp_handle)
| Writes a BMP to the screen immediately at an x and y offset.
MAGRESWCH_API void | DioWriteOLEDAreaBMPBuff (dio_handle_h nMasterHandle, dio_oled_write_mode_e mode, uint8_t x, uint8_t y, dio_bmp_h bmp_handle)
| Writes a BMP to the local screen buffer at an x and y offset.
MAGRESWCH_API void | DioWriteOLEDCharImm (dio_handle_h nMasterHandle, uint8_t x, uint8_t y, char letter)
| Writes a single character immediately to the screen.
MAGRESWCH_API void | DioWriteOLEDCharBuff (dio_handle_h nMasterHandle, dio_oled_write_mode_e mode, uint8_t x, uint8_t y, char letter)
| Writes a single character to the local screen buffer.
MAGRESWCH_API void | DioWriteOLEDStrImm (dio_handle_h nMasterHandle, uint8_t x, uint8_t y, char *str)
| Writes a string immediately to the screen.
MAGRESWCH_API void | DioWriteOLEDStrBuff (dio_handle_h nMasterHandle, dio_oled_write_mode_e mode, uint8_t x, uint8_t y, char *str)
| Writes a string to the local screen buffer.
MAGRESWCH_API const char * | DioGetErrorStr (dio_handle_h nMasterHandle, int16_t lpnStatus)
| Returns a null-terminated string associated with an `lpnStatus` error.

## Detailed Description

MAGResWCH DLL API for controlling the MAGRes board.

## Enumeration Type Documentation

## ◆ dio_errors_e

enum dio_errors_e

Errors represented by lpnStatus.

Enumerator
ERR_CANNOT_ALLOCATE_LPNMASTERHANDLE | Cannot allocate lpnMasterHandle.
ERR_INVALID_CH367_HANDLE | Invalid CH367 handle returned.
ERR_CANNOT_GET_IO_REG_ADDR | Cannot get io_reg address for the CH367.
ERR_STEP_SIZE_LESS_EQUAL_ZERO | Commanded step size is less than or equal to zero.
ERR_WRITE_LONGER_THAN_AVAIL_MEM | Number of bytes to write is larger than available memory.
ERR_WRITE_ZERO_BYTES | Number of bytes to write is zero, needs to be at least 1.
ERR_READ_ZERO_BYTES | Number of bytes to read is specified to be zero, needs to be at least 1.
ERR_SPI_READ_ERR | Cannot read SPI.
ERR_SPI_STREAM_ERR | Cannot stream SPI.
ERR_SPI_WRITE_ERR | Cannot write to the SPI.
ERR_SPI_ADDR_OUT_OF_BOUNDS | Tried to access an invalid SPI address.
ERR_BMP_INVALID_FILE | Tried to open invalid BMP file.

## ◆ dio_ext_trigger_modes_e

enum dio_ext_trigger_modes_e

External Trigger modes.

Enumerator
DIO_EXT_TRIG_IGNORE | Ignore the external trigger line.
DIO_EXT_TRIG_RISING_EDGE | Trigger and change state on the rising edge.
DIO_EXT_TRIG_FALLING_EDGE | Trigger and change state on the falling edge.
DIO_EXT_TRIG_HIGH_HOLD | Trigger and change state when the line is held high.
DIO_EXT_TRIG_LOW_HOLD | Trigger and change state when the line is held low.

## ◆ dio_oled_write_mode_e

enum dio_oled_write_mode_e

Pixel blending modes when using the OLED screen buffer.

Enumerator
DIO_OLED_MODE_OVERWRITE | Overwrites what's there.
DIO_OLED_MODE_OR | Or current pixel with new pixel value.
DIO_OLED_MODE_GREATER_THAN | Overwrite current pixel if new pixel is greater than existing pixel.
DIO_OLED_MODE_XOR | Xor current pixel with new pixel value.
DIO_OLED_MODE_NONZERO | Overwrite current pixel with new pixel value as long as the new value is nonzero.

## Function Documentation

## ◆ DioArm()

MAGRESWCH_API void DioArm | ( | dio_handle_h | nMasterHandle,
|  | int16_t * | lpnStatus )

Changes the board state from Halt to Pause.

The board must be in HALT state, otherwise it does nothing.

Parameters

  nMasterHandle | master board handle
  lpnStatus | return status, 0 on success, <0 on failure

## ◆ DioClearCtrlMemory()

MAGRESWCH_API void DioClearCtrlMemory | ( | dio_handle_h | nMasterHandle,
|  | int16_t * | lpnStatus )

Clears the control memory on the board.

Parameters

  nMasterHandle | master board handle
  lpnStatus | returned status, 0 on success < 0 on failure

## ◆ DioClearOLEDBuff()

MAGRESWCH_API void DioClearOLEDBuff | ( | dio_handle_h | nMasterHandle | ) |

Clears the current local screen buffer.

Parameters

  nMasterHandle | master board handle

## ◆ DIOClearOLEDImm()

MAGRESWCH_API void DIOClearOLEDImm | ( | dio_handle_h | nMasterHandle | ) |

Clears the screen immediately.

Parameters

  nMasterHandle | master board handle

## ◆ DioClearOutMemory()

MAGRESWCH_API void DioClearOutMemory | ( | dio_handle_h | nMasterHandle,
|  | int16_t * | lpnStatus )

Clears the output memory on the board.

Parameters

  nMasterHandle | master board handle
  lpnStatus | returned status, 0 on success < 0 on failure

## ◆ DioClose()

MAGRESWCH_API void DioClose | ( | dio_handle_h | nMasterHandle,
|  | int16_t * | lpnStatus )

Closes the connection to the board, and releases the handle from being used.

Passing a handle of 0 or NULL to DioClose will perform no action.

Parameters

  nMasterHandle | master board handle
  lpnStatus | returned status, 0 on success < 0 on failure

## ◆ DioCloseBMP()

MAGRESWCH_API void DioCloseBMP | ( | dio_handle_h | nMasterHandle,
|  | dio_bmp_h * | bmp_handle )

Closes and deallocates memory for a bitmap file.

Parameters

  nMasterHandle | master board handle
  bmp_handle | handle of the bmp file

## ◆ DioGetErrorStr()

MAGRESWCH_API const char * DioGetErrorStr | ( | dio_handle_h | nMasterHandle,
|  | int16_t | lpnStatus )

Returns a null-terminated string associated with an `lpnStatus` error.

Parameters

  nMasterHandle | master board handle
  lpnStatus | lpnStatus, assumed to be in error

Return values

  returns | null terminated error string

## ◆ DioHalt()

MAGRESWCH_API void DioHalt | ( | dio_handle_h | nMasterHandle,
|  | int16_t * | lpnStatus )

Changes specified master board state to HALT.

Change board program counter value to zero. Calling Dio Arm then DioTrig after the board is in a halt state will cause the board to run from the beginning.

Parameters

  nMasterHandle | master board handle
  lpnStatus | returned status, 0 on success < 0 on failure

## ◆ DioInitialize()

MAGRESWCH_API void DioInitialize | ( | short | nMasterNum,
|  | dio_handle_h * | lpnMasterHandle,
|  | int16_t * | lpnStatus )

Provides a one time initialization of a master board and all slave boards associated with it.

Returns the handle to the board.

Initialize the DIO system configuration with one command.

Parameters

  nMasterNum | number of the master board in the sytem.
  lpnMasterHandle | Returned master handle, 0 or NULL on error.
  lpnStatus | returned status, 0 on success, < 0 failure.

## ◆ DioOpenBMP()

MAGRESWCH_API dio_bmp_h DioOpenBMP | ( | dio_handle_h | nMasterHandle,
|  | char * | path,
|  | int16_t * | lpnStatus )

Opens and allocates memory for a bitmap file.

Parameters

  nMasterHandle | master board handle
  path | null terminated path to the file
  lpnStatus | returned status, 0 on success, < 0 failure.

Return values

  returns | a handle to the bmp data

## ◆ DioPause()

MAGRESWCH_API void DioPause | ( | dio_handle_h | nMasterHandle,
|  | int16_t * | lpnStatus )

Changes the specified master board state from a RUN to PAUSE state.

Board must be in a RUN state, otherwise the function does nothing.

Parameters

  nMasterHandle | master board handle
  lpnStatus | returned status, 0 on success, < 0 failure.

## ◆ DioReadCtrlMemory()

MAGRESWCH_API void DioReadCtrlMemory | ( | dio_handle_h | nHandle,
|  | uint32_t * | lnpdwVector,
|  | uint32_t | dwStart,
|  | uint32_t | dwSize,
|  | int16_t * | lpnStatus )

Reads a block of control memory from the specified board.

Board must be in a HALT state before calling these functions.

Parameters

  nHandle | master board handle
  lnpdwVector | Array of double words up to 16K elements
  dwStart | Starting address to read
  dwSize | Number of steps to read
  lpnStatus | returned status, 0 on success, < 0 failure, > 0 number of bytes read

## ◆ DioReadCurrentIO()

MAGRESWCH_API void DioReadCurrentIO | ( | dio_handle_h | nHandle,
|  | int32_t * | lpdwCounter,
|  | int16_t * | lpnStatus )

Returns the specified master board current output value.

Parameters

  nHandle | master board handle
  lpdwCounter | returned program counter value
  lpnStatus | returned status, 0 on success, < 0 failure, > 0 num bytes read

## ◆ DioReadMaxDataLines()

MAGRESWCH_API void DioReadMaxDataLines | ( | dio_handle_h | nHandle,
|  | int32_t * | lpdwCounter,
|  | int16_t * | lpnStatus )

Returns the specified master board max data lines available to program.

Parameters

  nHandle | master board handle
  lpdwCounter | returned data lines value
  lpnStatus | returned status, 0 on success, < 0 failure, > 0 num bytes read

## ◆ DioReadOutMemory()

MAGRESWCH_API void DioReadOutMemory | ( | dio_handle_h | nHandle,
|  | uint32_t * | lnpdwVector,
|  | uint32_t | dwStart,
|  | uint32_t | dwSize,
|  | int16_t * | lpnStatus )

Reads a block of output memory from the specified board.

Board must be in a HALT state before calling these functions.

Parameters

  nHandle | master board handle
  lnpdwVector | Array of double words up to 16K elements
  dwStart | Starting address to read
  dwSize | Number of steps to read
  lpnStatus | returned status, 0 on success, < 0 failure, > 0 number of bytes read

## ◆ DioReadProgramCounter()

MAGRESWCH_API void DioReadProgramCounter | ( | dio_handle_h | nHandle,
|  | int32_t * | lpdwCounter,
|  | int16_t * | lpnStatus )

Returns the specified master board program counter value.

Represents the address of the current step being executed.

Parameters

  nHandle | master board handle
  lpdwCounter | returned program counter value
  lpnStatus | returned status, 0 on success, < 0 failure, > 0 num bytes read

## ◆ DioReadSPI()

MAGRESWCH_API void DioReadSPI | ( | dio_handle_h | nMasterHandle,
|  | uint8_t | addr,
|  | uint8_t * | read_buff,
|  | size_t | len,
|  | int16_t * | lpnStatus )

Reads the SPI.

Accomplishes this by writing zeroes the SPI peripheral at the address, and fill `read_buff` with any incoming data

Address 0 is the FPGA, and it is recommended to use the DIO API to communicate with it.

Parameters

  nMasterHandle | master board handle
  addr | address of the SPI peripheral 0-7.
  write_buff | pointer to byte-array of what to write
  read_buff | pointer to byte-array of what to read
  len | length of both the read and write buffer
  lpnStatus | returned status, 0 on success < 0 on failure

## ◆ DioReadStatusRegister()

MAGRESWCH_API void DioReadStatusRegister | ( | dio_handle_h | nHandle,
|  | int16_t * | lpwData,
|  | int16_t * | lpnStatus )

Reads the status register from the specified board.

bits | id | description
--- | --- | ---
15-5 | R | Reserved
4-2 | STATE | board state: 000 HALT 011 Pause 1xx Run
1-0 | UNUSED |

Parameters

  nHandle | master board handle
  lpwData | returned status register value
  lpnStatus | returned status, 0 on success, < 0 failure.

## ◆ DioReset()

MAGRESWCH_API void DioReset | ( | dio_handle_h | nHandle,
|  | int16_t * | lpnStatus )

Changes state of specified master board to HALT.

Parameters

  nHandle | master board handle
  lpnStatus | returned status, 0 on success, < 0 failure.

## ◆ DioResetDDS()

MAGRESWCH_API void DioResetDDS | ( | dio_handle_h | nMasterHandle,
|  | int16_t * | lpnStatus )

Resets and initializes the DDS. Can only be sent during HALT.

Parameters

  nMasterHandle | master board handle
  lpnStatus | returned status, 0 on success < 0 on failure

## ◆ DioSendOLEDBuff()

MAGRESWCH_API void DioSendOLEDBuff | ( | dio_handle_h | nMasterHandle | ) |

Sends the current local screen buffer to the OLED screen.

Parameters

  nMasterHandle | master board handle

## ◆ DioSetupOLED()

MAGRESWCH_API void DioSetupOLED | ( | dio_handle_h | nMasterHandle,
|  | int16_t * | lpnStatus )

Sets up and turns on the OLED.

Must be called before any function manipulating the screen is called.

Parameters

  nMasterHandle | master board handle
  lpnStatus | returned status, 0 on success < 0 on failure

## ◆ DioSetupTriggerMode()

MAGRESWCH_API void DioSetupTriggerMode | ( | dio_handle_h | nMasterHandle,
|  | uint8_t | nPauseMode,
|  | uint8_t | nRunMode,
|  | int16_t * | lpnstatus )

Sets the external trigger mode during the PAUSE and RUN states.

The board can be triggered from an external line, but defaults to ignoring any changes on this external line. This function sets the action of the board in either the PAUSE or the RUN state. The different functionality is described in `dio_ext_trigger_modes_e`

The PAUSE state will transition to the RUN state depending on the value sent in `nPauseMode`. The RUN state will transition to the PAUSE state depending on the value sent in `nRunMode`.

Parameters

  nMasterHandle | master board handle
  nPauseMode | trigger mode during the pause state
  nRunMode | trigger mode during the run state
  lpnStatus | returned status, 0 on success < 0 on failure

## ◆ DioStep()

MAGRESWCH_API void DioStep | ( | dio_handle_h | nMasterHandle,
|  | int32_t | dwSteps,
|  | int16_t * | lpnStatus )

Executes the specified master board program for a number of steps.

Board must be in a PAUSE state.

Each step is executed by changing the board state from PAUSE to RUN state and then to PAUSE state again.

Parameters

  nMasterHandle | master board handle
  dwSteps | Number of steps to execute
  lpnStatus | returned status, 0 on success, < 0 failure.

## ◆ DioStreamSPI()

MAGRESWCH_API void DioStreamSPI | ( | dio_handle_h | nMasterHandle,
|  | uint8_t | addr,
|  | uint8_t * | write_buff,
|  | uint8_t * | read_buff,
|  | size_t | len,
|  | int16_t * | lpnStatus )

Streams the SPI.

Writes the contents of `write_buff` to the SPI peripheral at the given address, and read any incoming data that is coming in simultaneously to fill the `read_buff`.

Address 0 is the FPGA, and it is recommended to use the DIO API to communicate with it.

Parameters

  nMasterHandle | master board handle
  addr | address of the SPI peripheral 0-7.
  write_buff | pointer to byte-array of what to write
  read_buff | pointer to byte-array of what to read
  len | length of both the read and write buffer
  lpnStatus | returned status, 0 on success < 0 on failure

## ◆ DioTrig()

MAGRESWCH_API void DioTrig | ( | dio_handle_h | nMasterHandle,
|  | int16_t * | lpnStatus )

Takes the specified master board state from PAUSE to RUN.

Parameters

  nMasterHandle | master board handle
  lpnStatus | returned status, 0 on success, < 0 failure.

## ◆ DioWriteCtrlMemory()

MAGRESWCH_API void DioWriteCtrlMemory | ( | dio_handle_h | nHandle,
|  | uint32_t * | lpdwMemory,
|  | uint32_t | dwStart,
|  | uint32_t | dwSize,
|  | int16_t * | lpnStatus )

Writes a block of data to the control memory of the specified board.

Board must be in a HALT state before calling these functions.

Parameters

  nMasterHandle | master board handle
  lpdwMemory | array of double words
  dwStart | starting address to write
  dwSize | number of steps to write.
  lpnStatus | returned status, 0 on success, < 0 failure.

## ◆ DioWriteCurrentIO()

MAGRESWCH_API void DioWriteCurrentIO | ( | dio_handle_h | nHandle,
|  | int32_t | dwCounter,
|  | int16_t * | lpnStatus )

Writes the specified master board current output value.

The board must be in pause.

Parameters

  nHandle | master board handle
  dwCounter | new program counter value
  lpnStatus | returned status, 0 on success, < 0 failure, > 0 num bytes read

## ◆ DioWriteOLED2DUnpackedArrImm()

MAGRESWCH_API void DioWriteOLED2DUnpackedArrImm | ( | dio_handle_h | nMasterHandle,
|  | uint8_t ** | arr )

Writes 128x64 bytes to the screen at once, given a single dimensional array of that size.

The array MUST be that size, otherwise program will segfault.

Parameters

  nMasterHandle | master board handle
  arr | array to write

## ◆ DioWriteOLEDAreaArrBuff()

MAGRESWCH_API void DioWriteOLEDAreaArrBuff | ( | dio_handle_h | nMasterHandle,
|  | dio_oled_write_mode_e | mode,
|  | uint8_t | x,
|  | uint8_t | y,
|  | uint8_t | col_width,
|  | uint8_t | height,
|  | uint8_t * | arr )

Writes an array of length `col_width*height` to the local screen buffer.

The array is one dimensional, but written to the screen two-dimensionally at a y offset and single pixel offset in the x direction. The array is split into strips of `col_width`, and is written in `height` rows. The array should be formatted such that the first byte is the top-left of the image, and the last byte is the bottom right.

Undefined behavior if coordinates are outside bounds of display

Parameters

  nMasterHandle | master board handle
  mode | buffer overwrite mode
  x | x offset
  y | y offset
  col_width | width of image to write
  height | height of image to write
  arr | pointer to the array

## ◆ DioWriteOLEDAreaArrImm()

MAGRESWCH_API void DioWriteOLEDAreaArrImm | ( | dio_handle_h | nMasterHandle,
|  | uint8_t | x,
|  | uint8_t | y,
|  | uint8_t | col_width,
|  | uint8_t | height,
|  | uint8_t * | arr )

Writes an array of length `col_width*height` to the screen immediately.

The array is one dimensional, but written to the screen two-dimensionally at a y offset and single pixel offset in the x direction. The array is split into strips of `col_width`, and is written in `height` rows. The array should be formatted such that the first byte is the top-left of the image, and the last byte is the bottom right.

Undefined behavior if coordinates are outside bounds of display

Parameters

  nMasterHandle | master board handle
  mode | buffer overwrite mode
  x | x offset
  y | y offset
  col_width | width of image to write
  height | height of image to write
  arr | pointer to the array

## ◆ DioWriteOLEDAreaBMPBuff()

MAGRESWCH_API void DioWriteOLEDAreaBMPBuff | ( | dio_handle_h | nMasterHandle,
|  | dio_oled_write_mode_e | mode,
|  | uint8_t | x,
|  | uint8_t | y,
|  | dio_bmp_h | bmp_handle )

Writes a BMP to the local screen buffer at an x and y offset.

The origin of the BMP is the top left corner, and the offset is the distance between this corner and the BMP origin.

Parameters

  nMasterHandle | master board handle
  mode | buffer overwrite mode
  x | x offset
  y | y offset
  bmp_handle | handle of the bmp file

## ◆ DioWriteOLEDAreaBMPImm()

MAGRESWCH_API void DioWriteOLEDAreaBMPImm | ( | dio_handle_h | nMasterHandle,
|  | uint8_t | x,
|  | uint8_t | y,
|  | dio_bmp_h | bmp_handle )

Writes a BMP to the screen immediately at an x and y offset.

The origin of the BMP is the top left corner, and the offset is the distance between this corner and the BMP origin.

Parameters

  nMasterHandle | master board handle
  x | x offset
  y | y offset
  bmp_handle | handle of the bmp file

## ◆ DioWriteOLEDArrBuff()

MAGRESWCH_API void DioWriteOLEDArrBuff | ( | dio_handle_h | nMasterHandle,
|  | dio_oled_write_mode_e | mode,
|  | uint8_t | x,
|  | uint8_t | y,
|  | uint8_t * | arr,
|  | size_t | len )

Writes an array of length len to the local screen buffer.

The array is written to the screen at a y offset and single pixel offset in the x direction, nibble calculations to move the array across by one pixel are done internally.

Undefined behavior if coordinates are outside bounds of display

Parameters

  nMasterHandle | master board handle
  mode | buffer overwrite mode
  x | x offset
  y | y offset
  arr | pointer to the array
  len | length of the array

## ◆ DioWriteOLEDArrImm()

MAGRESWCH_API void DioWriteOLEDArrImm | ( | dio_handle_h | nMasterHandle,
|  | uint8_t | x,
|  | uint8_t | y,
|  | uint8_t * | arr,
|  | size_t | len )

Writes an array of length len to screen immediately.

The array is written to the screen at a y offset and single pixel offset in the x direction, nibble calculations to move the array across by one pixel are done internally.

Undefined behavior if coordinates are outside bounds of display

Parameters

  nMasterHandle | master board handle
  x | x offset
  y | y offset
  arr | pointer to the array
  len | length of the array

## ◆ DioWriteOLEDCharBuff()

MAGRESWCH_API void DioWriteOLEDCharBuff | ( | dio_handle_h | nMasterHandle,
|  | dio_oled_write_mode_e | mode,
|  | uint8_t | x,
|  | uint8_t | y,
|  | char | letter )

Writes a single character to the local screen buffer.

Parameters

  nMasterHandle | master board handle
  x | x offset
  y | y offset
  letter | letter to write

## ◆ DioWriteOLEDCharImm()

MAGRESWCH_API void DioWriteOLEDCharImm | ( | dio_handle_h | nMasterHandle,
|  | uint8_t | x,
|  | uint8_t | y,
|  | char | letter )

Writes a single character immediately to the screen.

Parameters

  nMasterHandle | master board handle
  x | x offset
  y | y offset
  letter | letter to write

## ◆ DioWriteOLEDLineBuff()

MAGRESWCH_API void DioWriteOLEDLineBuff | ( | dio_handle_h | nMasterHandle,
|  | dio_oled_write_mode_e | mode,
|  | uint8_t | x1,
|  | uint8_t | y1,
|  | uint8_t | x2,
|  | uint8_t | y2,
|  | uint8_t | val1,
|  | uint8_t | val2 )

Writes a line to the local screen buffer that begins at (x1, y1), with value `val1`, to (x2, y2) with value `val2`.

`val1` and `val2` are linearly interpolated.

Undefined behavior if coordinates are outside bounds of display

Parameters

  nMasterHandle | master board handle
  mode | buffer overwrite mode
  x1 | starting x value
  y1 | starting y value
  x2 | ending x value
  y2 | ending y value
  val1 | starting brightness value
  val2 | ending brightness value

## ◆ DioWriteOLEDLineImm()

MAGRESWCH_API void DioWriteOLEDLineImm | ( | dio_handle_h | nMasterHandle,
|  | uint8_t | x1,
|  | uint8_t | y1,
|  | uint8_t | x2,
|  | uint8_t | y2,
|  | uint8_t | val1,
|  | uint8_t | val2 )

Immediately writes a line to the screen that begins at (x1, y1), with value `val1`, to (x2, y2) with value `val2`.

`val1` and `val2` are linearly interpolated.

Undefined behavior if coordinates are outside bounds of display

Parameters

  nMasterHandle | master board handle
  x1 | starting x value
  y1 | starting y value
  x2 | ending x value
  y2 | ending y value
  val1 | starting brightness value
  val2 | ending brightness value

## ◆ DioWriteOLEDPixelBuff()

MAGRESWCH_API void DioWriteOLEDPixelBuff | ( | dio_handle_h | nMasterHandle,
|  | dio_oled_write_mode_e | mode,
|  | uint8_t | x,
|  | uint8_t | y,
|  | uint8_t | val )

Writes a pixel to the screen at the designated coordinate in the local screen buffer.

Out of bounds values wrap around.

Parameters

  nMasterHandle | master board handle
  mode | buffer overwrite mode
  x | pixel x value, 0-256
  y | pixel row
  val | pixel pair value, the upper nibble being the leftmost

## ◆ DioWriteOLEDPixelImm()

MAGRESWCH_API void DioWriteOLEDPixelImm | ( | dio_handle_h | nMasterHandle,
|  | uint8_t | row,
|  | uint8_t | column,
|  | uint8_t | val )

Writes a pixel to the screen at the designated coordinate immediately.

Out of bounds values wrap around.

Parameters

  nMasterHandle | master board handle
  x | pixel x value, 0-256
  y | pixel row
  val | pixel pair value, the upper nibble being the leftmost

## ◆ DioWriteOLEDPixelPairBuff()

MAGRESWCH_API void DioWriteOLEDPixelPairBuff | ( | dio_handle_h | nMasterHandle,
|  | dio_oled_write_mode_e | mode,
|  | uint8_t | column,
|  | uint8_t | y,
|  | uint8_t | val )

Writes a value to a pair of pixels in the local screen buffer.

This is not written to the screen until the buffer is sent to the device. The x position of the pixel pair is a column, and goes from 0-127, since every column is two pixels wide. Pixel rows are indexed as follows: zero being the top of the screen, 63 being the lowest part of the screen.

Parameters

  nMasterHandle | master board handle
  mode | buffer overwrite mode
  column | pixel column
  y | pixel row
  val | pixel pair value, the upper nibble being the leftmost pixel

## ◆ DioWriteOLEDPixelPairImm()

MAGRESWCH_API void DioWriteOLEDPixelPairImm | ( | dio_handle_h | nMasterHandle,
|  | uint8_t | column,
|  | uint8_t | y,
|  | uint8_t | val )

Writes a value to a pair of pixels immediately.

The x position of the pixel pair is a column, and goes from 0-127, since every column is two pixels wide. Pixel rows are indexed as follows: zero being the top of the screen, 63 being the lowest part of the screen

Parameters

  nMasterHandle | master board handle
  column | pixel column
  y | pixel row
  val | pixel pair value, the upper nibble being the leftmost pixel

## ◆ DioWriteOLEDRowArrBuff()

MAGRESWCH_API void DioWriteOLEDRowArrBuff | ( | dio_handle_h | nMasterHandle,
|  | dio_oled_write_mode_e | mode,
|  | uint8_t | y,
|  | uint8_t * | arr )

Writes an array of length 128 to a row in the local screen buffer.

The array is written to the screen at a y offset.

Parameters

  nMasterHandle | master board handle
  y | y offset
  arr | pointer to the array

## ◆ DioWriteOLEDRowArrImm()

MAGRESWCH_API void DioWriteOLEDRowArrImm | ( | dio_handle_h | nMasterHandle,
|  | uint8_t | y,
|  | uint8_t * | arr )

Writes an array of length 128 to a row on screen immediately.

The array is written to the screen at a y offset.

Parameters

  nMasterHandle | master board handle
  y | y offset
  arr | pointer to the array

## ◆ DioWriteOLEDRowValImm()

MAGRESWCH_API void DioWriteOLEDRowValImm | ( | dio_handle_h | nMasterHandle,
|  | uint8_t | y,
|  | uint8_t | val )

Writes singular value to a row on screen immediately.

The value is written to the screen at a y offset.

Parameters

  nMasterHandle | master board handle
  y | y offset
  val | value to write

## ◆ DioWriteOLEDScreenArrBuff()

MAGRESWCH_API void DioWriteOLEDScreenArrBuff | ( | dio_handle_h | nMasterHandle,
|  | dio_oled_write_mode_e | mode,
|  | uint8_t * | arr )

Writes 128x64 bytes to the local screen buffer, given a single dimensional array of that size.

Each byte represents two pixels, the upper nibble representing the leftmost pixel of the byte. The array MUST be that size, otherwise program will segfault.

Parameters

  nMasterHandle | master board handle
  mode | buffer overwrite mode
  arr | array to write

## ◆ DioWriteOLEDScreenArrImm()

MAGRESWCH_API void DioWriteOLEDScreenArrImm | ( | dio_handle_h | nMasterHandle,
|  | uint8_t * | arr )

Writes 128x64 bytes to the screen at once, given a single dimensional array of that size.

Each byte represents two pixels, the upper nibble representing the leftmost pixel of the byte. The array MUST be that size, otherwise program will segfault.

Parameters

  nMasterHandle | master board handle
  arr | array to write

## ◆ DioWriteOLEDStrBuff()

MAGRESWCH_API void DioWriteOLEDStrBuff | ( | dio_handle_h | nMasterHandle,
|  | dio_oled_write_mode_e | mode,
|  | uint8_t | x,
|  | uint8_t | y,
|  | char * | str )

Writes a string to the local screen buffer.

Parameters

  nMasterHandle | master board handle
  x | x offset
  y | y offset
  str | string to write

## ◆ DioWriteOLEDStrImm()

MAGRESWCH_API void DioWriteOLEDStrImm | ( | dio_handle_h | nMasterHandle,
|  | uint8_t | x,
|  | uint8_t | y,
|  | char * | str )

Writes a string immediately to the screen.

Parameters

  nMasterHandle | master board handle
  x | x offset
  y | y offset
  str | string to write

## ◆ DioWriteOutMemory()

MAGRESWCH_API void DioWriteOutMemory | ( | dio_handle_h | nHandle,
|  | uint32_t * | lpdwMemory,
|  | uint32_t | dwStart,
|  | uint32_t | dwSize,
|  | int16_t * | lpnStatus )

Writes a block of data to the output memory of the specified board.

Board must be in a HALT state before calling these functions.

Parameters

  nMasterHandle | master board handle
  lpdwMemory | array of double words
  dwStart | starting address to write
  dwSize | number of steps to write.
  lpnStatus | returned status, 0 on success, < 0 failure.

## ◆ DioWriteProgramCounter()

MAGRESWCH_API void DioWriteProgramCounter | ( | dio_handle_h | nHandle,
|  | int32_t | dwCounter,
|  | int16_t * | lpnStatus )

Writes the specified master board program counter value.

The board must be in pause state for this function to be successful.

Parameters

  nHandle | master board handle
  dwCounter | new program counter value
  lpnStatus | returned status, 0 on success, < 0 failure, > 0 num bytes read

## ◆ DioWriteSPI()

MAGRESWCH_API void DioWriteSPI | ( | dio_handle_h | nMasterHandle,
|  | uint8_t | addr,
|  | uint8_t * | write_buff,
|  | size_t | len,
|  | int16_t * | lpnStatus )

Writes to the SPI.

Writes the `write_buff` to the SPI peripheral at the address, and ignore any any incoming data

Address 0 is the FPGA, and it is recommended to use the DIO API to communicate with it.

Parameters

  nMasterHandle | master board handle
  addr | address of the SPI peripheral 0-7.
  write_buff | pointer to byte-array of what to write
  len | length of both the read and write buffer
  lpnStatus | returned status, 0 on success < 0 on failure