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

#include <stdint.h>

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

Macros

Typedefs

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ dio_errors_e

◆ dio_ext_trigger_modes_e

◆ dio_oled_write_mode_e

Function Documentation

◆ DioArm()

◆ DioClearCtrlMemory()

◆ DioClearOLEDBuff()

◆ DIOClearOLEDImm()

◆ DioClearOutMemory()

◆ DioClose()

◆ DioCloseBMP()

◆ DioGetErrorStr()

◆ DioHalt()

◆ DioInitialize()

◆ DioOpenBMP()

◆ DioPause()

◆ DioReadCtrlMemory()

◆ DioReadCurrentIO()

◆ DioReadMaxDataLines()

◆ DioReadOutMemory()

◆ DioReadProgramCounter()

◆ DioReadSPI()

◆ DioReadStatusRegister()

◆ DioReset()

◆ DioResetDDS()

◆ DioSendOLEDBuff()

◆ DioSetupOLED()

◆ DioSetupTriggerMode()

◆ DioStep()

◆ DioStreamSPI()

◆ DioTrig()

◆ DioWriteCtrlMemory()

◆ DioWriteCurrentIO()

◆ DioWriteOLED2DUnpackedArrImm()

◆ DioWriteOLEDAreaArrBuff()

◆ DioWriteOLEDAreaArrImm()

◆ DioWriteOLEDAreaBMPBuff()

◆ DioWriteOLEDAreaBMPImm()

◆ DioWriteOLEDArrBuff()

◆ DioWriteOLEDArrImm()

◆ DioWriteOLEDCharBuff()

◆ DioWriteOLEDCharImm()

◆ DioWriteOLEDLineBuff()

◆ DioWriteOLEDLineImm()

◆ DioWriteOLEDPixelBuff()

◆ DioWriteOLEDPixelImm()

◆ DioWriteOLEDPixelPairBuff()

◆ DioWriteOLEDPixelPairImm()

◆ DioWriteOLEDRowArrBuff()

◆ DioWriteOLEDRowArrImm()

◆ DioWriteOLEDRowValImm()

◆ DioWriteOLEDScreenArrBuff()

◆ DioWriteOLEDScreenArrImm()

◆ DioWriteOLEDStrBuff()

◆ DioWriteOLEDStrImm()

◆ DioWriteOutMemory()

◆ DioWriteProgramCounter()

◆ DioWriteSPI()