stream.h

Go to the documentation of this file.

/*
  stream.h - high level (serial) stream handling
 
  Part of grblHAL
 
  Copyright (c) 2019-2025 Terje Io
 
  grblHAL is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.
 
  grblHAL is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  GNU General Public License for more details.
 
  You should have received a copy of the GNU General Public License
  along with grblHAL. If not, see <http://www.gnu.org/licenses/>.
*/
 
#ifndef _STREAM_H_
#define _STREAM_H_
 
#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"
 
#ifndef RX_BUFFER_SIZE
#define RX_BUFFER_SIZE 1024 // must be a power of 2
#endif
 
#ifndef TX_BUFFER_SIZE
#define TX_BUFFER_SIZE 512  // must be a power of 2
#endif
 
#ifndef BLOCK_TX_BUFFER_SIZE
#define BLOCK_TX_BUFFER_SIZE 256
#endif
 
// Serial baud rate
#ifndef BAUD_RATE
#define BAUD_RATE 115200
#endif
 
// Value to be returned from input stream when no data is available
#ifndef SERIAL_NO_DATA
#define SERIAL_NO_DATA -1
#endif
 
#define BUFNEXT(ptr, buffer) ((ptr + 1) & (sizeof(buffer.data) - 1))
#define BUFCOUNT(head, tail, size) ((head >= tail) ? (head - tail) : (size - tail + head))
 
#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>
 
#include "vfs.h"
 
typedef enum {
    StreamType_Serial = 0,
    StreamType_MPG,
    StreamType_Bluetooth,
    StreamType_Telnet,
    StreamType_WebSocket,
    StreamType_SDCard, // deprecated, use StreamType_File instead
    StreamType_File = StreamType_SDCard,
    StreamType_Redirected,
    StreamType_Null
} stream_type_t;
 
typedef enum {
    StreamSuspend_Off = 0,
    StreamSuspend_Pending,
    StreamSuspend_Active
} stream_suspend_state_t;
 
typedef enum {
    Serial_8bit = 0,
    Serial_7bit
} serial_width_t;
 
typedef enum {
    Serial_StopBits1 = 0,
    Serial_StopBits1_5,
    Serial_StopBits2,
    Serial_StopBits0_5,
} serial_stopbits_t;
 
typedef enum {
    Serial_ParityNone = 0,
    Serial_ParityEven,
    Serial_ParityOdd,
    Serial_ParityMark,
    Serial_ParitySpace,
} serial_parity_t;
 
typedef union {
    uint8_t value;
    struct {
        uint8_t width    :2,
                stopbits :2,
                parity   :3,
                unused   :1;
    };
} serial_format_t;
 
typedef union {
    uint8_t value;
    struct {
        uint8_t dtr    :1,
                rts    :1,
                unused :6;
    };
} serial_linestate_t;
 
typedef bool (*stream_is_connected_ptr)(void);
 
typedef uint16_t (*get_stream_buffer_count_ptr)(void);
 
typedef int32_t (*stream_read_ptr)(void);
 
typedef void (*stream_write_ptr)(const char *s);
 
typedef void (*stream_write_n_ptr)(const uint8_t *s, uint16_t len);
 
 
typedef bool (*stream_write_char_ptr)(const uint8_t c);
 
typedef bool (*enqueue_realtime_command_ptr)(uint8_t c);
 
typedef void (*stream_set_direction_ptr)(bool tx);
 
typedef bool (*enqueue_realtime_command2_ptr)(uint8_t c);
 
 
typedef enqueue_realtime_command_ptr (*set_enqueue_rt_handler_ptr)(enqueue_realtime_command_ptr handler);
 
typedef bool (*set_format_ptr)(serial_format_t format);
 
typedef bool (*set_baud_rate_ptr)(uint32_t baud_rate);
 
typedef void (*flush_stream_buffer_ptr)(void);
 
typedef void (*cancel_read_buffer_ptr)(void);
 
typedef bool (*suspend_read_ptr)(bool await);
 
typedef bool (*disable_rx_stream_ptr)(bool disable);
 
typedef void (*on_linestate_changed_ptr)(serial_linestate_t state);
 
typedef union {
    uint8_t value;
    struct {
        uint8_t claimable     :1,
                claimed       :1,
                can_set_baud  :1,
                rx_only       :1,
                modbus_ready  :1,
                rts_handshake :1,
                init_ok       :1,
                unused        :1;
    };
} io_stream_flags_t;
 
typedef union {
    uint8_t value;
    struct {
        uint8_t webui_connected :1,
                is_usb          :1,
                linestate_event :1, 
                passthru        :1, 
                unused          :4;
    };
} io_stream_state_t;
 
typedef struct {
    stream_type_t type;                                     
    uint8_t instance;                                       
    io_stream_state_t state;                                
    stream_is_connected_ptr is_connected;                   
    get_stream_buffer_count_ptr get_rx_buffer_free;         
    stream_write_ptr write;                                 
    stream_write_ptr write_all;                             
    stream_write_char_ptr write_char;                       
    enqueue_realtime_command2_ptr enqueue_rt_command;       
    stream_read_ptr read;                                   
    flush_stream_buffer_ptr reset_read_buffer;              
    cancel_read_buffer_ptr cancel_read_buffer;              
    set_enqueue_rt_handler_ptr set_enqueue_rt_handler;      
    suspend_read_ptr suspend_read;                          
    stream_write_n_ptr write_n;                             
    disable_rx_stream_ptr disable_rx;                       
    get_stream_buffer_count_ptr get_rx_buffer_count;        
    get_stream_buffer_count_ptr get_tx_buffer_count;        
    flush_stream_buffer_ptr reset_write_buffer;             
    set_baud_rate_ptr set_baud_rate;                        
    set_format_ptr set_format;                              
    stream_set_direction_ptr set_direction;                 
    on_linestate_changed_ptr on_linestate_changed;          
    vfs_file_t *file;                                       
} io_stream_t;
 
typedef struct {
    io_stream_state_t state;                                
    io_stream_flags_t flags;                                
    uint32_t baud_rate;
    serial_format_t format;
} io_stream_status_t;
 
typedef const io_stream_t *(*stream_claim_ptr)(uint32_t baud_rate);
typedef bool (*stream_release_ptr)(uint8_t instance);
typedef const io_stream_status_t *(*stream_get_status_ptr)(uint8_t instance);
 
typedef struct {
    stream_type_t type;                                     
    uint8_t instance;                                       
    io_stream_flags_t flags;
    stream_claim_ptr claim;
    stream_release_ptr release;
    stream_get_status_ptr get_status;                       
} io_stream_properties_t;
 
typedef bool (*stream_enumerate_callback_ptr)(io_stream_properties_t const *properties);
 
typedef struct io_stream_details {
    uint8_t n_streams;
    io_stream_properties_t *streams;
    struct io_stream_details *next;
} io_stream_details_t;
 
// The following structures and functions are not referenced in the core code, may be used by drivers
 
typedef struct {
    volatile uint_fast16_t head;
    volatile uint_fast16_t tail;
    volatile bool rts_state;
    bool overflow;
    bool backup;
    uint8_t data[RX_BUFFER_SIZE];
} stream_rx_buffer_t;
 
typedef struct {
    volatile uint_fast16_t head;
    volatile uint_fast16_t tail;
    uint8_t data[TX_BUFFER_SIZE];
} stream_tx_buffer_t;
 
typedef struct {
    uint_fast16_t length;
    uint_fast16_t max_length;
    uint8_t *s;
    uint8_t data[BLOCK_TX_BUFFER_SIZE];
} stream_block_tx_buffer_t;
 
// double buffered tx stream
typedef struct {
    uint_fast16_t length;
    uint_fast16_t max_length;
    uint8_t *s;
    bool use_tx2data;
    uint8_t data[BLOCK_TX_BUFFER_SIZE];
    uint8_t data2[BLOCK_TX_BUFFER_SIZE];
} stream_block_tx_buffer2_t;
 
#ifdef __cplusplus
extern "C" {
#endif
 
int32_t stream_get_null (void);
 
 bool stream_rx_suspend (stream_rx_buffer_t *rxbuffer, bool suspend);
 
 stream_suspend_state_t stream_is_rx_suspended (void);
 
bool stream_mpg_register (const io_stream_t *stream, bool rx_only, stream_write_char_ptr write_char);
 
bool stream_mpg_enable (bool on);
 
void stream_mpg_set_mode (void *data);
 
bool stream_mpg_check_enable (char c);
 
bool stream_buffer_all (uint8_t c);
 
bool stream_tx_blocking (void);
 
bool stream_enqueue_realtime_command (uint8_t 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);
 
void stream_set_defaults (const io_stream_t *stream, uint32_t baud_rate);
 
const io_stream_t *stream_get_base (void);
 
io_stream_flags_t stream_get_flags (io_stream_t stream);
 
const io_stream_status_t *stream_get_uart_status (uint8_t instance);
 
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_close (io_stream_t const *stream);
bool stream_set_description (const io_stream_t *stream, const char *description);
 
void debug_printf(const char *fmt, ...);
 
#if defined(DEBUG) || defined(DEBUGOUT)
#define DEBUG_PRINT 1
#ifdef DEBUGOUT
void debug_write (const char *s);
void debug_writeln (const char *s);
bool debug_stream_init (void);
#endif
#else
#define DEBUG_PRINT 0
#endif
 
#define debug_print(fmt, ...) \
   do { if(DEBUG_PRINT) debug_printf(fmt, __VA_ARGS__); } while(0)
 
#ifdef __cplusplus
}
#endif
 
#endif