stream.h File Reference

#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>
#include "vfs.h"

Go to the source code of this file.

Data Structures
union	serial_linestate_t
union	io_stream_flags_t
union	io_stream_state_t
struct	io_stream_t
	Properties and handlers for stream I/O. More...
struct	io_stream_properties_t
struct	io_stream_details
struct	stream_rx_buffer_t
struct	stream_tx_buffer_t
struct	stream_block_tx_buffer_t
struct	stream_block_tx_buffer2_t

Macros
#define	ASCII_SOH   0x01
#define	ASCII_STX   0x02
#define	ASCII_ETX   0x03
#define	ASCII_EOT   0x04
#define	ASCII_ENQ   0x05
#define	ASCII_ACK   0x06
#define	ASCII_BS   0x08
#define	ASCII_TAB   0x09
#define	ASCII_LF   0x0A
#define	ASCII_CR   0x0D
#define	ASCII_XON   0x11
#define	ASCII_XOFF   0x13
#define	ASCII_NAK   0x15
#define	ASCII_EOF   0x1A
#define	ASCII_CAN   0x18
#define	ASCII_EM   0x19
#define	ASCII_ESC   0x1B
#define	ASCII_DEL   0x7F
#define	ASCII_EOL   "\r\n"
#define	RX_BUFFER_SIZE   1024
#define	TX_BUFFER_SIZE   512
#define	BLOCK_TX_BUFFER_SIZE   256
#define	BAUD_RATE   115200
#define	SERIAL_NO_DATA   -1
#define	BUFNEXT(ptr, buffer)   ((ptr + 1) & (sizeof(buffer.data) - 1))
#define	BUFCOUNT(head, tail, size)   ((head >= tail) ? (head - tail) : (size - tail + head))
#define	DEBUG_PRINT   0
#define	debug_print(fmt, ...)    do { if(DEBUG_PRINT) debug_printf(fmt, __VA_ARGS__); } while(0)

Typedefs
typedef bool(*	stream_is_connected_ptr) (void)
	Pointer to function for getting stream connected status. More...
typedef uint16_t(*	get_stream_buffer_count_ptr) (void)
	Pointer to function for getting number of characters available or free in a stream buffer. More...
typedef int16_t(*	stream_read_ptr) (void)
	Pointer to function for reading a single character from a input stream. More...
typedef void(*	stream_write_ptr) (const char *s)
	Pointer to function for writing a null terminated string to the output stream. More...
typedef void(*	stream_write_n_ptr) (const char *s, uint16_t len)
	Pointer to function for writing a n character long string to the output stream. More...
typedef bool(*	stream_write_char_ptr) (const char c)
	Pointer to function for writing a single character to the output stream. More...
typedef bool(*	enqueue_realtime_command_ptr) (char c)
	Pointer to function for extracting real-time commands from the input stream and enqueue them for processing. This should be called by driver code prior to inserting a character into the input buffer. More...
typedef bool(*	enqueue_realtime_command2_ptr) (char c)
	Optional, but recommended, pointer to function for enqueueing realtime command characters. More...
typedef enqueue_realtime_command_ptr(*	set_enqueue_rt_handler_ptr) (enqueue_realtime_command_ptr handler)
	Pointer to function for setting the enqueue realtime commands handler. More...
typedef bool(*	set_baud_rate_ptr) (uint32_t baud_rate)
	Pointer to function for setting the stream baud rate. More...
typedef void(*	flush_stream_buffer_ptr) (void)
	Pointer to function for flushing a stream buffer. More...
typedef void(*	cancel_read_buffer_ptr) (void)
	Pointer to function for flushing the input buffer and inserting an ASCII_CAN character. More...
typedef bool(*	suspend_read_ptr) (bool await)
	Pointer to function for blocking reads from and restoring a input buffer. More...
typedef bool(*	disable_rx_stream_ptr) (bool disable)
	Pointer to function for disabling/enabling stream input. More...
typedef void(*	on_linestate_changed_ptr) (serial_linestate_t state)
	Pointer to function for handling line state changed events. More...
typedef const io_stream_t *(*	stream_claim_ptr) (uint32_t baud_rate)
typedef bool(*	stream_enumerate_callback_ptr) (io_stream_properties_t const *properties)
typedef struct io_stream_details	io_stream_details_t

Enumerations
enum	stream_type_t {   StreamType_Serial = 0 , StreamType_MPG , StreamType_Bluetooth , StreamType_Telnet ,   StreamType_WebSocket , StreamType_SDCard , StreamType_File = StreamType_SDCard , StreamType_Redirected ,   StreamType_Null }

Functions
int16_t	stream_get_null (void)
	Dummy function for reading data from a virtual empty input buffer. More...
bool	stream_rx_suspend (stream_rx_buffer_t *rxbuffer, bool suspend)
	Function for blocking reads from or restoring an input buffer. More...
bool	stream_mpg_register (const io_stream_t *stream, bool rx_only, stream_write_char_ptr write_char)
bool	stream_mpg_enable (bool on)
	Function for enabling/disabling input from a secondary input stream. More...
void	stream_mpg_set_mode (void *data)
bool	stream_mpg_check_enable (char c)
bool	stream_buffer_all (char c)
bool	stream_tx_blocking (void)
bool	stream_enqueue_realtime_command (char c)
void	stream_register_streams (io_stream_details_t *details)
bool	stream_enumerate_streams (stream_enumerate_callback_ptr callback)
bool	stream_connect (const io_stream_t *stream)
bool	stream_connect_instance (uint8_t instance, uint32_t baud_rate)
void	stream_disconnect (const io_stream_t *stream)
bool	stream_connected (void)
const io_stream_t *	stream_get_base (void)
io_stream_flags_t	stream_get_flags (io_stream_t stream)
const io_stream_t *	stream_null_init (uint32_t baud_rate)
io_stream_t const *	stream_open_instance (uint8_t instance, uint32_t baud_rate, stream_write_char_ptr rx_handler, const char *description)
bool	stream_set_description (const io_stream_t *stream, const char *description)
void	debug_printf (const char *fmt,...)

Detailed Description

Stream I/O functions structure for the HAL.

Helper functions for saving away and restoring a stream input buffer. Not referenced by the core.

Macro Definition Documentation

ASCII_ACK

#define ASCII_ACK   0x06

ASCII_BS

#define ASCII_BS   0x08

ASCII_CAN

#define ASCII_CAN   0x18

ASCII_CR

#define ASCII_CR   0x0D

ASCII_DEL

#define ASCII_DEL   0x7F

ASCII_EM

#define ASCII_EM   0x19

ASCII_ENQ

#define ASCII_ENQ   0x05

ASCII_EOF

#define ASCII_EOF   0x1A

ASCII_EOL

#define ASCII_EOL   "\r\n"

ASCII_EOT

#define ASCII_EOT   0x04

ASCII_ESC

#define ASCII_ESC   0x1B

ASCII_ETX

#define ASCII_ETX   0x03

ASCII_LF

#define ASCII_LF   0x0A

ASCII_NAK

#define ASCII_NAK   0x15

ASCII_SOH

#define ASCII_SOH   0x01

ASCII_STX

#define ASCII_STX   0x02

ASCII_TAB

#define ASCII_TAB   0x09

ASCII_XOFF

#define ASCII_XOFF   0x13

ASCII_XON

#define ASCII_XON   0x11

BAUD_RATE

#define BAUD_RATE   115200

BLOCK_TX_BUFFER_SIZE

#define BLOCK_TX_BUFFER_SIZE   256

BUFCOUNT

#define BUFCOUNT	(		head,
			tail,
			size
	)		((head >= tail) ? (head - tail) : (size - tail + head))

BUFNEXT

#define BUFNEXT	(		ptr,
			buffer
	)		((ptr + 1) & (sizeof(buffer.data) - 1))

DEBUG_PRINT

#define DEBUG_PRINT   0

debug_print

#define debug_print	(		fmt,
			...
	)		do { if(DEBUG_PRINT) debug_printf(fmt, __VA_ARGS__); } while(0)

RX_BUFFER_SIZE

#define RX_BUFFER_SIZE   1024

SERIAL_NO_DATA

#define SERIAL_NO_DATA   -1

TX_BUFFER_SIZE

#define TX_BUFFER_SIZE   512

Typedef Documentation

cancel_read_buffer_ptr

typedef void(* cancel_read_buffer_ptr) (void)

Pointer to function for flushing the input buffer and inserting an ASCII_CAN character.

This function is typically called by the enqueue_realtime_command handler when CMD_STOP or CMD_JOG_CANCEL character is processed. The ASCII_CAN character might be checked for and used by upstream code to flush any buffers it may have.

disable_rx_stream_ptr

typedef bool(* disable_rx_stream_ptr) (bool disable)

Pointer to function for disabling/enabling stream input.

Typically used to disable receive interrupts so that real-time command processing for the stream is blocked. Usually it is desirable to block processing when another stream provides the input, but sometimes not. E.g. when input is from a SD card real-time commands from the stream that initiated SD card streaming is needed for handing feed-holds, overrides, soft resets etc.

Parameters

disable

true to disable stream, false to enable,

enqueue_realtime_command2_ptr

typedef bool(* enqueue_realtime_command2_ptr) (char c)

Optional, but recommended, pointer to function for enqueueing realtime command characters.

Parameters

c	character to enqueue.

Returns

true if successfully enqueued, false otherwise.

NOTE: Stream implementations should pass the character over the current handler registered by the set_enqueue_rt_handler().

User or plugin code should not enqueue realtime command characters via this handler, it should call grbl.enqueue_realtime_command() instead.

enqueue_realtime_command_ptr

typedef bool(* enqueue_realtime_command_ptr) (char c)

Pointer to function for extracting real-time commands from the input stream and enqueue them for processing. This should be called by driver code prior to inserting a character into the input buffer.

Parameters

c	character to check.

Returns

true if extracted, driver code should not insert the character into the input buffer if so.

flush_stream_buffer_ptr

typedef void(* flush_stream_buffer_ptr) (void)

Pointer to function for flushing a stream buffer.

get_stream_buffer_count_ptr

typedef uint16_t(* get_stream_buffer_count_ptr) (void)

Pointer to function for getting number of characters available or free in a stream buffer.

Returns

number of characters available or free.

io_stream_details_t

typedef struct io_stream_details io_stream_details_t

on_linestate_changed_ptr

typedef void(* on_linestate_changed_ptr) (serial_linestate_t state)

Pointer to function for handling line state changed events.

Parameters

set_baud_rate_ptr

typedef bool(* set_baud_rate_ptr) (uint32_t baud_rate)

Pointer to function for setting the stream baud rate.

Parameters

baud_rate

Returns

true if successful.

set_enqueue_rt_handler_ptr

typedef enqueue_realtime_command_ptr(* set_enqueue_rt_handler_ptr) (enqueue_realtime_command_ptr handler)

Pointer to function for setting the enqueue realtime commands handler.

Parameters

handler

a enqueue_realtime_command_ptr pointer to the new handler function.

Returns

enqueue_realtime_command_ptr pointer to the replaced function.

NOTE: Stream implementations should hold a pointer to the handler in a local variable and typically set it to protocol_enqueue_realtime_command() on initialization.

stream_claim_ptr

typedef const io_stream_t*(* stream_claim_ptr) (uint32_t baud_rate)

stream_enumerate_callback_ptr

typedef bool(* stream_enumerate_callback_ptr) (io_stream_properties_t const *properties)

stream_is_connected_ptr

typedef bool(* stream_is_connected_ptr) (void)

Pointer to function for getting stream connected status.

Returns

true connected, false otherwise.

stream_read_ptr

typedef int16_t(* stream_read_ptr) (void)

Pointer to function for reading a single character from a input stream.

Returns

character or -1 if none available.

stream_write_char_ptr

typedef bool(* stream_write_char_ptr) (const char c)

Pointer to function for writing a single character to the output stream.

Parameters

c	the character to write.

stream_write_n_ptr

typedef void(* stream_write_n_ptr) (const char *s, uint16_t len)

Pointer to function for writing a n character long string to the output stream.

Parameters

s	pointer to string.
len	number of characters to write.

stream_write_ptr

typedef void(* stream_write_ptr) (const char *s)

Pointer to function for writing a null terminated string to the output stream.

Parameters

s	pointer to null terminated string.

NOTE: output might be buffered until an ASCII_LF is output, this is usually done by USB or network driver code to improve throughput.

suspend_read_ptr

typedef bool(* suspend_read_ptr) (bool await)

Pointer to function for blocking reads from and restoring a input buffer.

This function is called with the await parameter true on executing a tool change command (M6), this shall block further reading from the input buffer. The core function stream_rx_suspend() can be called with the await parameter to do this, it will replace the hal.stream.read handler with a pointer to the dummy function stream_get_null().

Reading from the input is blocked until a tool change acknowledge character CMD_TOOL_ACK is received, when the driver receives this the input buffer is to be saved away and reading from the input resumed by restoring the hal.stream.read handler with its own read character function. Driver code can do this by calling the core function stream_rx_backup().

When the tool change is complete or a soft reset is executed the core will call this function with the await parameter false, if the driver code called stream_rx_suspend() to block input it shall then call it again with the await parameter as input to restore it.

Parameters

await

bool

Returns

true if there is data in the buffer, false otherwise.

Enumeration Type Documentation

stream_type_t

enum stream_type_t

Enumerator
StreamType_Serial
StreamType_MPG
StreamType_Bluetooth
StreamType_Telnet
StreamType_WebSocket
StreamType_SDCard
StreamType_File
StreamType_Redirected
StreamType_Null

Function Documentation

debug_printf()

void debug_printf	(	const char *	fmt,
			...
	)

stream_buffer_all()

bool stream_buffer_all

(

char

c

)

stream_connect()

bool stream_connect

(

const io_stream_t *

stream

)

stream_connect_instance()

bool stream_connect_instance	(	uint8_t	instance,
		uint32_t	baud_rate
	)

stream_connected()

bool stream_connected

(

void

)

stream_disconnect()

void stream_disconnect

(

const io_stream_t *

stream

)

stream_enqueue_realtime_command()

bool stream_enqueue_realtime_command

(

char

c

)

stream_enumerate_streams()

bool stream_enumerate_streams

(

stream_enumerate_callback_ptr

callback

)

stream_get_base()

const io_stream_t* stream_get_base

(

void

)

stream_get_flags()

io_stream_flags_t stream_get_flags

(

io_stream_t

stream

)

stream_get_null()

int16_t stream_get_null

(

void

)

Dummy function for reading data from a virtual empty input buffer.

Returns

always -1 as there is no data available.

stream_mpg_check_enable()

bool stream_mpg_check_enable

(

char

c

)

stream_mpg_enable()

bool stream_mpg_enable

(

bool

on

)

Function for enabling/disabling input from a secondary input stream.

Parameters

on	true if switching input to mpg stream, false when restoring original input.

Returns

true when succsessful, false otherwise.

stream_mpg_register()

bool stream_mpg_register	(	const io_stream_t *	stream,
		bool	rx_only,
		stream_write_char_ptr	write_char
	)

stream_mpg_set_mode()

void stream_mpg_set_mode

(

void *

data

)

stream_null_init()

const io_stream_t* stream_null_init

(

uint32_t

baud_rate

)

stream_open_instance()

io_stream_t const* stream_open_instance	(	uint8_t	instance,
		uint32_t	baud_rate,
		stream_write_char_ptr	rx_handler,
		const char *	description
	)

stream_register_streams()

void stream_register_streams

(

io_stream_details_t *

details

)

stream_rx_suspend()

bool stream_rx_suspend	(	stream_rx_buffer_t *	rxbuffer,
		bool	suspend
	)

Function for blocking reads from or restoring an input buffer.

Parameters

rxbuffer	pointer to a stream_rx_buffer_t.
suspend	when true hal.stream.read is changed to stream_get_null(), if false it is restored if already saved.

Returns

true if there is data in the buffer, false otherwise.

stream_set_description()

bool stream_set_description	(	const io_stream_t *	stream,
		const char *	description
	)

stream_tx_blocking()

bool stream_tx_blocking

(

void

)