stream.h

Go to the documentation of this file.

/*
  stream.h - high level (serial) stream handling
 
  Part of grblHAL
 
  Copyright (c) 2019-2026 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_File,
    StreamType_SDCard = StreamType_File, // deprecated, use StreamType_File instead
    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,
                dsr    :1,
                rts    :1,
                cts    :1,
                unused :4;
    };
} serial_linestate_t;
 
typedef enum {
    Report_ClearAll = 0,
    Report_MPGMode = (1 << 0),
    Report_Scaling = (1 << 1),
    Report_Homed   = (1 << 2),
    Report_LatheXMode = (1 << 3),
    Report_Spindle = (1 << 4),
    Report_Coolant = (1 << 5),
    Report_Overrides = (1 << 6),
    Report_Tool = (1 << 7),
    Report_WCO = (1 << 8),
    Report_GWCO = (1 << 9),
    Report_ToolOffset = (1 << 10),
    Report_M66Result = (1 << 11),
    Report_PWM = (1 << 12),
    Report_Motor = (1 << 13),
    Report_Encoder = (1 << 14),
    Report_TLOReference = (1 << 15),
    Report_Fan = (1 << 16),
    Report_SpindleId = (1 << 17),
    Report_ProbeId = (1 << 18),
    Report_DistanceToGo = (1 << 19),
    Report_ProbeProtect = (1 << 20),
    Report_ForceWCO = (1 << 29),
    Report_CycleStart = (1 << 30),
    Report_All = 0x801FFFFF
} report_tracking_t;
 
typedef union {
    uint32_t value;
    struct {
        uint32_t mpg_mode       :1, 
                 scaling        :1, 
                 homed          :1, 
                 xmode          :1, 
                 spindle        :1, 
                 coolant        :1, 
                 overrides      :1, 
                 tool           :1, 
                 wco            :1, 
                 gwco           :1, 
                 tool_offset    :1, 
                 m66result      :1, 
                 pwm            :1, 
                 motor          :1, 
                 encoder        :1, 
                 tlo_reference  :1, 
                 fan            :1, 
                 spindle_id     :1, 
                 probe_id       :1, 
                 distance_to_go :1, 
                 probe_protect  :1, 
                 unassigned     :8, //
                 force_wco      :1, 
                 cycle_start    :1, 
                 all            :1; 
    };
} report_tracking_flags_t;
 
typedef struct {
    report_tracking_flags_t flags;
    uint8_t override_counter;       
    uint8_t wco_counter;            
} status_report_tracking_t;
 
struct io_stream_properties;
typedef struct io_stream_properties io_stream_properties_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)(io_stream_properties_t *stream, 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,
                is_usb        :1;
    };
} io_stream_flags_t;
 
typedef union {
    uint8_t value;
    struct {
        uint8_t webui_connected   :1,
                is_usb            :1,
                linestate_event   :1, 
                passthru          :1, 
                utf8              :1, 
                eof               :1, 
                m98_macro_prescan :1, 
                unused            :1;
    };
} 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;                 
    vfs_file_t *file;                                       
// The following fields are kept over a stream change
    status_report_tracking_t report;                        
    on_linestate_changed_ptr on_linestate_changed;          
} 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);
 
struct io_stream_properties {
    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;                       
};
 
typedef bool (*stream_enumerate_callback_ptr)(io_stream_properties_t const *properties, void *data);
 
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
 
static inline bool stream_is_uart (stream_type_t type)
{
    return type == StreamType_Serial || type == StreamType_Bluetooth;
}
 
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 (uint8_t 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, void *data);
 
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);
 
bool stream_await_tx_clear (const io_stream_t *stream);
 
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);
 
void stream_usb_linestate_changed (uint8_t instance, serial_linestate_t state);
 
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