noodle.h File Reference

CNN/ML primitives for tiny MCUs with pluggable filesystem backends. More...

#include <stdint.h>
#include "noodle_config.h"
#include "noodle_fs.h"

Include dependency graph for noodle.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	Conv
	File-backed convolution parameters. More...
struct	ConvMem
	Memory-backed convolution parameters. More...
struct	Pool
	2D pooling parameters. Use M = 1 and T = 1 for identity (no pooling). More...
struct	FCN
struct	FCNFile
struct	FCNMem

Typedefs
typedef unsigned char	byte
	Minimal Arduino-compatible alias when not building for Arduino.
typedef void(*	CBFPtr) (float progress)
	Progress callback type used by long-running routines.

Enumerations
enum	Activation : uint8_t { ACT_NONE = 0 , ACT_RELU = 1 , ACT_SOFTMAX = 2 }

Functions
Common parameter semantics
Standard meanings shared by many functions. Parameters W Input spatial width (2D) or length (1D). K Kernel size (2D: KxK, 1D: K). S Stride. P Zero-padding (per side). 2D uses top/left padding of size P. M Pool kernel size (2D: MxM). T Pool stride. n_inputs Number of input channels/features. n_outputs Number of output channels/features. in_fn Base input filename template (see File naming convention). out_fn Base output filename template. weight_fn Weight filename template; receives both I and O indices. bias_fn Bias filename (one bias per output channel, scalar per line). with_relu If true, apply ReLU after bias.
void	noodle_setup_temp_buffers (void *b1, void *b2)
	Provide two reusable temporary buffers used internally by file-streaming operations.Must be called before conv/FCN variants that read from files. Two temp buffers are needed for operations that read from a file. For C*W*W tensor, the buffer should be W*W.
void	noodle_setup_temp_buffers (void *b2)
	Provide a single reusable temporary buffer used internally by file-streaming ops.Must be called before conv/FCN variants that read from files. One temp buffer is needed for operations that reads from a variable. Hence, only output accumulator buffe is needed. For C*W*W tensor, the buffer should be W*W.
File and File-System Utilities
bool	noodle_fs_init (uint8_t clk_pin, uint8_t cmd_pin, uint8_t d0_pin)
	Initialize SD/FS backend (pins variant is meaningful only for SD_MMC).
bool	noodle_fs_init (uint8_t clk_pin, uint8_t cmd_pin, uint8_t d0_pin, uint8_t d1_pin, uint8_t d2_pin, uint8_t d3_pin)
	Initialize SD/FS backend with default pins/settings.
bool	noodle_fs_init ()
bool	noodle_fs_init (uint8_t cs_pin)
	Initialize SD/FS backend with a specific CS_PIN.
void	noodle_read_top_line (const char *fn, char *line, size_t maxlen)
	Read the first line of a given text file.
void	noodle_delete_file (const char *fn)
	Delete a file if it exists.
size_t	noodle_read_bytes_until (NDL_File &file, char terminator, char *buffer, size_t length)
	Read bytes from a file until a terminator or length-1 (NULL terminated).
Scalar I/O helpers
void	noodle_write_float (NDL_File &f, float d)
float	noodle_read_float (NDL_File &f)
	Read a float up to the next newline.
byte	noodle_read_byte (NDL_File &f)
	Read a byte value fron an opened file handler and store as an integer text line.
void	noodle_write_byte (NDL_File &f, byte d)
	Write a byte value as an integer text line to an opend file.
Memory utilities
float *	noodle_create_buffer (uint16_t size)
	Allocate a raw float buffer of size bytes.
void	noodle_delete_buffer (float *buffer)
	Free a buffer allocated by noodle_create_buffer.
void	noodle_reset_buffer (float *buffer, uint16_t n)
	Fill buffer with zeros (n floats).
float *	noodle_slice (float *flat, size_t W, size_t z)
void	noodle_array_to_file (float *array, const char *fn, uint16_t n)
	Write an array of n floats to fn, one value per line. File will be opened and closed.
void	noodle_array_to_file (float *array, NDL_File &fo, uint16_t n)
	Write an array of n floats to fo (an opened file handler), one value per line. No file open and close operations.
void	noodle_grid_to_file (byte *grid, const char *fn, uint16_t n)
	Write an n×n byte grid to fn as bytes, row-major. File will be opened and closed.
void	noodle_grid_to_file (byte *grid, NDL_File &fo, uint16_t n)
	Write an n×n byte grid to fo (opened file handler) as bytes, row-major. No file open and close operations.
void	noodle_grid_to_file (float *grid, const char *fn, uint16_t n)
	Write an n×n float grid to fn, row-major.
void	noodle_grid_to_file (float *grid, NDL_File &fo, uint16_t n)
	Write an n×n float grid to fo (an opened file handler), row-major.
void	noodle_array_from_file (const char *fn, float *buffer, uint16_t K)
	Read a float array of length K from fn (one value per line).
void	noodle_array_from_file (NDL_File &fi, float *buffer, uint16_t K)
	Read a float array of length K from an opened file handler fi (one value per line).
void	noodle_grid_from_file (const char *fn, byte *buffer, uint16_t K)
void	noodle_grid_from_file (NDL_File &fi, byte *buffer, uint16_t K)
	Read an K × K grid (stored as byte) from fi (opened file handler) into buffer.
void	noodle_grid_from_file (const char *fn, int8_t *buffer, uint16_t K)
	Read an K × K grid (stored as float) from fn into buffer.
void	noodle_grid_from_file (NDL_File &fi, int8_t *buffer, uint16_t K)
	Read an K × K grid (stored as int8) from fi (opened file handler) into buffer.
void	noodle_grid_from_file (const char *fn, float *buffer, uint16_t K)
	Read an K × K grid (stored as float) from fn into buffer.
void	noodle_grid_from_file (NDL_File &fi, float *buffer, uint16_t K)
Internal Helpers for Pooling
uint16_t	noodle_do_pooling (const float *input, uint16_t W, uint16_t K, uint16_t S, const char *fn)
	2D pooling over a V×V map, writing results to a file (one float per line).Pooling mode (MAX or MEAN) is selected via NOODLE_POOL_MODE at compile time. This layer uses valid pooling. NO PADDING IS APPLIED!
uint16_t	noodle_do_pooling (const float *input, uint16_t W, uint16_t K, uint16_t S, NDL_File &fo)
uint16_t	noodle_do_pooling (const float *input, uint16_t W, uint16_t K, uint16_t S, float *output)
uint16_t	noodle_do_pooling1d (float *input, uint16_t W, uint16_t K, uint16_t S, const char *fn)
uint16_t	noodle_do_pooling1d (float *input, uint16_t W, uint16_t K, uint16_t S, NDL_File &fo)
2D Convolution
Packed-file conventions: Input file: packed CHW planes (each plane W×W). Output file: packed CHW planes (each plane V_out×V_out) in output-channel order. Padding: Noodle uses symmetric, stride-independent padding. If P >= 0, that value is used as the symmetric padding on all sides. If P == 65535, padding is computed automatically as: P = floor((K - 1) / 2) which preserves spatial size when S = 1 and K is odd. Requires temporary buffers set via noodle_setup_temp_buffers. Buffer sizes are typically W×W floats, used as per-channel scratch space.
uint16_t	noodle_conv_byte (const char *in_fn, uint16_t n_inputs, uint16_t n_outputs, const char *out_fn, uint16_t W, const Conv &conv, const Pool &pool, CBFPtr progress_cb=NULL)
	File→File 2D conv with BYTE input feature maps.
uint16_t	noodle_conv_float (const char *in_fn, uint16_t n_inputs, uint16_t n_outputs, const char *out_fn, uint16_t W, const Conv &conv, const Pool &pool, CBFPtr progress_cb=NULL)
	File→File 2D conv with FLOAT input feature maps.
uint16_t	noodle_conv_float (const char *in_fn, uint16_t n_inputs, uint16_t n_outputs, float *output, uint16_t W, const Conv &conv, const Pool &pool, CBFPtr progress_cb=NULL)
	File→Memory 2D conv with FLOAT inputs; writes [O, Wo, Wo] tensor to output.
uint16_t	noodle_conv_float (float *input, uint16_t n_inputs, uint16_t n_outputs, const char *out_fn, uint16_t W, const Conv &conv, const Pool &pool, CBFPtr progress_cb=NULL)
	Memory→File 2D conv with FLOAT inputs and in-file conv parameters.
uint16_t	noodle_conv_float (float *input, uint16_t n_inputs, uint16_t n_outputs, const char *out_fn, uint16_t W, const ConvMem &conv, const Pool &pool, CBFPtr progress_cb=NULL)
	Memory→File 2D conv with FLOAT inputs and in-varibale conv parameters.
uint16_t	noodle_conv_float (float *input, uint16_t n_inputs, uint16_t n_outputs, float *output, uint16_t W, const Conv &conv, const Pool &pool, CBFPtr progress_cb=NULL)
	Memory→Memory 2D conv with FLOAT inputs and in-file conv parameters.
uint16_t	noodle_conv_float (float *input, uint16_t n_inputs, uint16_t n_outputs, float *output, uint16_t W, const ConvMem &conv, const Pool &pool, CBFPtr progress_cb=NULL)
1D Convolution
Conv.K used as kernel length W used as input length
uint16_t	noodle_conv1d (const char *in_fn, uint16_t n_inputs, const char *out_fn, uint16_t n_outputs, uint16_t W, const Conv &conv, const Pool &pool, CBFPtr progress_cb=NULL)
uint16_t	noodle_conv1d (const char *in_fn, uint16_t n_inputs, const char *out_fn, uint16_t n_outputs, uint16_t W, const Conv &conv, CBFPtr progress_cb=NULL)
uint16_t	noodle_conv1d (const char *in_fn, uint16_t n_inputs, const char *out_fn, uint16_t n_outputs, uint16_t W, const ConvMem &conv, CBFPtr progress_cb)
uint16_t	noodle_conv1d (float *in, uint16_t n_inputs, float *out, uint16_t n_outputs, uint16_t W, const ConvMem &conv, CBFPtr progress_cb=NULL)
uint16_t	noodle_conv1d (float *in, uint16_t n_inputs, const char *out_fn, uint16_t n_outputs, uint16_t W, const ConvMem &conv, CBFPtr progress_cb)
uint16_t	noodle_conv1d (const char *in_fn, uint16_t n_inputs, float *out, uint16_t n_outputs, uint16_t W, const ConvMem &conv, CBFPtr progress_cb)
Internal Helpers for Convolution
uint16_t	noodle_do_conv1d (float *input, float *kernel, uint16_t W, uint16_t K, float *output, uint16_t P, uint16_t S)
uint16_t	noodle_do_conv (byte *grid, const float *kernel, uint16_t K, uint16_t W, float *output, uint16_t P, uint16_t S)
	2D valid/same convolution with zero padding and stride, accumulating into output.Output spatial size is V = (W - K + 2P)/S + 1.
uint16_t	noodle_do_conv (float *grid, const float *kernel, uint16_t K, uint16_t W, float *output, uint16_t P, uint16_t S)
uint16_t	noodle_do_bias (float *output, float bias, uint16_t n)
uint16_t	noodle_do_bias_act (float *output, float bias, uint16_t n, Activation act)
	Add bias to each element of a V×V map (in-place) and optionally apply activation.
float	noodle_get_padded_x (byte *grid, int16_t i, int16_t j, int16_t W, int16_t P)
	Get padded input sample from a byte grid with zero padding.Noodle uses symmetric, stride-independent padding for all convolutions.
float	noodle_get_padded_x (float *grid, int16_t i, int16_t j, int16_t W, int16_t P)
	Get padded input sample from a float grid with zero padding.
Activations
uint16_t	noodle_soft_max (float *input_output, uint16_t n)
uint16_t	noodle_sigmoid (float *input_output, uint16_t n)
uint16_t	noodle_relu (float *input_output, uint16_t n)
Fully Connected Network
uint16_t	noodle_fcn (const int8_t *input, uint16_t n_inputs, uint16_t n_outputs, const char *out_fn, const FCNFile &fcn, CBFPtr progress_cb=NULL)
uint16_t	noodle_fcn (const char *in_fn, uint16_t n_inputs, uint16_t n_outputs, const char *out_fn, const FCNFile &fcn, CBFPtr progress_cb=NULL)
uint16_t	noodle_fcn (const float *input, uint16_t n_inputs, uint16_t n_outputs, float *output, const FCNMem &fcn, CBFPtr progress_cb=NULL)
uint16_t	noodle_fcn (const byte *input, uint16_t n_inputs, uint16_t n_outputs, float *output, const FCNFile &fcn, CBFPtr progress_cb=NULL)
uint16_t	noodle_fcn (const int8_t *input, uint16_t n_inputs, uint16_t n_outputs, float *output, const FCNFile &fcn, CBFPtr progress_cb=NULL)
uint16_t	noodle_fcn (const char *in_fn, uint16_t n_inputs, uint16_t n_outputs, float *output, const FCNFile &fcn, CBFPtr progress_cb=NULL)
uint16_t	noodle_fcn (const float *input, uint16_t n_inputs, uint16_t n_outputs, float *output, const FCNFile &fcn, CBFPtr progress_cb)
uint16_t	noodle_fcn (const float *input, uint16_t n_inputs, uint16_t n_outputs, const char *out_fn, const FCNFile &fcn, CBFPtr progress_cb)
Tensor Reshaping
uint16_t	noodle_flat (const char *in_fn, float *output, uint16_t V, uint16_t n_filters)
uint16_t	noodle_flat (float *input, float *output, uint16_t V, uint16_t n_filters)
uint16_t	noodle_gap (float *inout, uint16_t C, uint16_t W)
void	noodle_find_max (float *input, uint16_t n, float &max_val, uint16_t &max_idx)
2D Depth-wise Convolution
uint16_t	noodle_dwconv_float (const char *in_fn, uint16_t n_channels, const char *out_fn, uint16_t W, const Conv &conv, const Pool &pool, CBFPtr progress_cb)
uint16_t	noodle_dwconv_float (float *input, uint16_t n_channels, float *output, uint16_t W, const Conv &conv, const Pool &pool, CBFPtr progress_cb)
uint16_t	noodle_dwconv_float (float *input, uint16_t n_channels, float *output, uint16_t W, const ConvMem &conv, const Pool &pool, CBFPtr progress_cb)
void	noodle_unpack_bn_params (const float *bn_params, uint16_t C, const float **gamma, const float **beta, const float **mean, const float **var)
Batch Normalization
uint16_t	noodle_bn (float *x, uint16_t C, uint16_t W, const float *gamma, const float *beta, const float *mean, const float *var, float eps=1e-3)
uint16_t	noodle_bn_relu (float *x, uint16_t C, uint16_t W, const float *gamma, const float *beta, const float *mean, const float *var, float eps=1e-3)
uint16_t	noodle_bn (float *x, uint16_t C, uint16_t W, const float *bn_params, float eps=1e-3)
uint16_t	noodle_bn_relu (float *x, uint16_t C, uint16_t W, const float *bn_params, float eps=1e-3)

Detailed Description

CNN/ML primitives for tiny MCUs with pluggable filesystem backends.

Noodle provides minimal convolution, pooling, flatten, fully-connected and activation routines that operate either entirely in memory or by streaming tensors/parameters to and from a filesystem (SD/FFat/SD_MMC). Backends are selected in noodle_fs.h via preprocessor flags. The library is designed for extremely small RAM budgets, so most file-based APIs reuse two caller-supplied temporary buffers (see noodle_setup_temp_buffers).

Backends

Select exactly one backend flag before including this header: NOODLE_USE_SDFAT, NOODLE_USE_SD_MMC, NOODLE_USE_FFAT, or NOODLE_USE_LITTLEFS. See noodle_fs.h for backend details and required platform libraries.

Temporary buffers

Call noodle_setup_temp_buffers() once prior to convolution/FCN routines that read from files. Unless otherwise stated:

• temp buffer #1: at least W*W*sizeof(float) bytes
• temp buffer #2: at least W*W*sizeof(float) bytes (accumulator)

Tensor layout and file format

File-based APIs use packed CHW by default: channel-major planes stored back-to-back. Each plane is stored in row-major order as whitespace-separated numeric tokens (ASCII).

• Packed 2D feature map file: [ch0 W×W][ch1 W×W]...[ch(C-1) W×W]
• Packed 1D feature map file: [ch0 W][ch1 W]...[ch(C-1) W]
• Weights file (Conv): ordered by output-major then input: (O0,I0) kernel, (O0,I1) kernel, ...
• Bias file: one scalar per output channel (n_outputs values).

## Convolution

All convolutions in Noodle use symmetric padding.

Pooling mode

2D pooling mode is compile-time selectable via NOODLE_POOL_MODE in noodle_config.h (MAX or MEAN).

Typedef Documentation

byte

typedef unsigned char byte

Minimal Arduino-compatible alias when not building for Arduino.

Enumeration Type Documentation

Activation

enum Activation : uint8_t

Enumerator
ACT_NONE
ACT_RELU
ACT_SOFTMAX