ustd

ustd provides minimal and highly portable implementations of the following classes:

• ustd::array, a lightweight c++11 array implementation (ustd_array.h).
• ustd::queue, a lightweight c++11 queue implementation (ustd_queue.h).
• ustd::map, a lightweight c++11 map implementation (ustd_map.h).

The libraries are header-only and should work with any c++11 compiler and support platforms starting with 8k attiny, avr, arduinos, up to esp8266, esp32 and mac and linux.

• ustd_functional.h provides a drop-in replacement for std::function<> for AVRs: ustd::function<> for low-resource AVRs (see project functional-avr)

Documentation: ustd:: documentation

Platform defines

Make sure to use the appropriate platform define before including from ustd.

Platform	#define (by user)	Comment
ATtiny	__ATTINY__	For very low resource ATMELs
Arduino	__UNO__	Should work with low resource arduinos
Arduino	__ATMEGA__	Should work with most arduinos
FeatherM0	__FEATHER_M0__	Adafruit feather M0 (Wifi)
RP PICO	__RP2040__	Raspberry Pi PICO RP2040
FeatherM4	__FEATHER_M4__	Adafruit feather M4 (Wifi)
STM32	__BLUEPILL__	STM32F103C8T6 ARM Cortex-M3
STM32	__BLACKPILL__	STM32F411 ARM Cortex-M4
NRF52	__NRF52__	Feather NRF52832 Cortex-M4
Teensy40	__TEENSY40__	Teensy 4.0 Cortex-M7
Nano33BLE	__NANOBLE__	Arduino Nano 33 BLE (Sense) nRF52840
ESP8266	__ESP__	For ESP8266 and ESP32
ESP32	__ESP32__	ESP32
ESP32-C3	__ESP32_RISC_	ESP32-C3 (RISC-V)
ESP32DEV	__ESP32DEV__	ESP32 git head
Maix Bit	__MAIXBIT__	Sipeed Maix Bit RISC-V
Longan	__LONGAN_NANO__	Sipeed Longan Nano RISC-V
Mac	__APPLE__	Should be defined already
Linux	__linux__	Should be defined already

Note: If the desired MCU is not in that list, select one with similar characteristics, these platform defines are used to generate feature-lists that are used by muwerk's modules.

Additional selectable options

Option	Comment
USTD_OPTION_FS_FORCE_SPIFFS	to continue to use old SPIFFS instead of LittleFS. New default for ESP8266 is LittleFS.
USTD_OPTION_FS_FORCE_NO_FS	Disable all filesystem related functionality
USTD_OPTION_FS_FORCE_LITTLEFS	switch to LittleFS on ESP32 (currently SPIFFS is still used as default for tensilica-based ESPs for compatibility reasons). New ESP32 cores have LittleFS support. For ESP32_RISC cores (e.g. ESP32-C3), LITTLEFS is ALWAYS used, since there is no legacy.

Defines generated by ustd_platform.h depending on the platform define above

Note: All defines below are automatically generated, they are derived from the platform define above:

Family defines

Platform define	Automatically defined family	Comment
__UNO__	__ARDUINO__	8-bit Atmel Arduinos
__MEGA__	__ARDUINO__	"
__FEATHER_MO__	__ARM__	ARM cortex
__RP2040__	__ARM__, __RP_PICO__	"
__FEATHER_M4__	__ARM__	"
__BLUEPILL__	__ARM__	"
__BLACKPILL__	__ARM__	"
__NRF52__	__ARM__	"
__TEENSY40__	__ARM__	"
__NANOBLE__	__ARM__	"
__ESP__	__TENSILICA__	Espressif Tensilica
__ESP32__	__TENSILICA__	"
__ESPDEV__	__TENSILICA__	"
__ESP32_RISC__	__RISC_V__	RISC-V ESP32-C3
__MAIXBIT__	__RISC_V__	RISC-V based MCUs
__LONGAN_NANO__	__RISC_V__	RISC-V based MCUs
__APPLE__	__UNIXOID__	macOS computer
__linux__	__UNIXOID__	Linux computer

Features

Define	Comment
USTD_FEATURE_MEMORY	This is set to a class of available memory, see below for possible values.
USTD_FEATURE_FILESYSTEM	The system has a filesystem, muwerk APIs defined in filesystem.h and jsonfile.h are available.
USTD_FEATURE_FS_SPIFFS	Filesystem is SPIFFS format (legacy ESP8266 and all ESP32 with tensilica cores)
USTD_FEATURE_FS_LITTLEFS	Filesystem is LittleFS (standard for ESP8266 and ESP32C3 RISC-V)
USTD_FEATURE_FS_SD	Future: SD Filesystem
USTD_FEATURE_EEPROM	Platform has EEPROM storage
USTD_FEATURE_SYSTEMCLOCK	System has a clock
USTD_FEATURE_CLK_READ	Time can be read
USTD_FEATURE_CLK_SET	Time can be set
USTD_FEATURE_NETWORK	Network access available
USTD_FEATURE_FREE_MEMORY	freeMemory() is available
USTD_FEATURE_SUPPORTS_NEW_OPERATOR	Platform SDK has it's own new operator

Possible values for USTD_FEATURE_MEMORY

(Automatically derived by ustd_platform.h from platform define __xxx__)

Value	Example platform
USTD_FEATURE_MEM_512B	ATtiny85
USTD_FEATURE_MEM_2K	Arduino UNO, ATtiny1614, AT328P
USTD_FEATURE_MEM_8K	Arduino MEGA
USTD_FEATURE_MEM_32K	ESP8266, Bluepill, Cortex M0, M3, M4F
USTD_FEATURE_MEM_128K	Blackpill, ESP32
USTD_FEATURE_MEM_512K
USTD_FEATURE_MEM_1M	Unixoids & RISC-V

To make code dependent on a memory-class, use something like:

#if USTD_FEATURE_MEMORY >= USTD_FEATURE_MEM_2K
// Feature that requires at least 2k RAM
#endif

Example

// first a platform define (see table above):
#define __ESP32__
#include "ustd_array.h"

const int ci[]={1,2,3,4,5};
ustd::array<int> ia(ci,5);
for (auto i : ia) {
    printf("%d\n",i);
}

Installation

ustd is available via Arduino library manager or platformio:

• Arduino ustd
• Platformio ustd, library ID 5710.

Complete example

See Examples for a complete build example with ustd and linux, Arduino-IDE or platformio.

Related projects

• ustd is used by muwerk to implement a portable cooperative scheduler with MQTT-like communication queues.

History

• 0.7.5 (2023-07-30) Sipeed Longan RISC-V
• 0.7.4 (2022-10-17) Support for ESP32-C3 (RISC-V), tested with Adafruit QTPY ESP32-C3, platform define __ESP32_RISC__. 'Legacy' ESPs automatically define family __TENSILICA__, whereas the new RISC-V based chip defines family __RISC_V__. Note: __ESP32_RISC__ always uses LittleFS!
• 0.7.3 (2022-08-26) Minimal doc fixes.
• 0.7.2 (2022-08-04) New option USTD_OPTION_FS_FORCE_LITTLEFS for ESP32. Switches to LittleFS for new cores. For compatibility reasons currently default file system for ESP32 is still SPIFFS.
• 0.7.1 (2022-05-03) Teensy 4.0 support (#20, thanks @SteveEisner).
• 0.7.0 (2021-10-19) Slight breaking change in array-read handling: Earlier versions allowed read-operations to grow (thus mutating) the array, if the array was initialized as growing. Changed via #17, thanks @mzanetti.
• 0.6.2 (2021-06-07) Support multiple inclusion of global operators / functions in one submodule (Thanks @mo22, #13)
• 0.6.1 (2021-02-26) Initial Raspberry PICO rp2040 support.
• 0.6.0 (2021-02-09) New platforms, iterator and copy-constructor support.
  • Support for iterators and copy-constructors in ustd::array, ustd::queue, and ustd::map. (Thanks proddy for iterator sample implementation.)
  • Platforms: Feather M4 added: __FEATHER_M4__
  • Blackpill STM32F411 added.
  • Arduino Nano 33 BLE added. Note: requires platformio's lib_ldf_mode = chain+ definition in platform.ini, otherwise platformio will get confused about including WiFi.h, because of faulty #ifdef parsing of ustd_platformio.h.
  • ASSERT() macros removed due to clashes.
• 0.5.0 (2021-01-30) BREAKING CHANGE: In order to prevent name-clashes for include-files for Arduino-IDE users, all ustd include files now have an ustd_ prefix. Compatibility-versions without ustd_ that include the ustd_ versions are provided, with exception of queue.h (clash with ESP8266-Wifi) and platform.h (clash with RISC-V sdk).
• CI (2021-01-28) Use Github actions to test build for all platform defines.
• 0.4.4 (2021-01-25) Missing USTD_FEATURE_FILESYSTEM defines for ESPs added.
• 0.4.2 (2021-01-24) New platforms __FEATHER_M0__ (ARM Cortex M0), __BLUEPILL__ (ARM Cortex M3), __NRF42__ (ARM Cortex M4F), __MAIXBIT__ (RISC-V). Bugfix for zero-initialisation of array, map, and queue (no longer uses memset).
• 0.4.1 (2021-01-22) Bugfix for USTD_FEATURE_MEMORY handling. ATtiny no longer supports ustd::function<>.
• 0.4.0 (2021-01-19) Feature defines in ustd_platform.h for better hardware specific adaptations.
• 0.3.6 (2021-01-12) Support for UNO and MEGA in functional.h via __ARDUINO__ define.
• 0.3.5 (2021-01-12) New function freeMemory(), new platform define __UNO__. (Both __UNO__ and __ATMEGA__ implicitly define __ARDUINO__)
• 0.3.4 (2021-01-11) Small documentation fixes.
• 0.3.3 (2021-01-08) ustd::array::resize() did not correctly update the array size, which would lead to memory corrupts (tuxpoldo). Improvements for debug macros.
• 0.3.2 (2021-01-07) More consistent debug interface using DBG() macros (see ustd_platform.h), fixes to USTD_ASSERT macro that was inconsistently named ASSERTS.
• 0.3.1 (2020-12-25) More SPIFFS vs LittleFS preparations
• 0.3.0 (2020-10-26) Cleanup ustd_platform.h: ESP32 continues to use SPIFFS by default, ESP8266 LittleFS (since SPIFFS is deprecated for ESP8266, and LittleFS is not (yet) available for ESP32). This is a breaking change for ESP8266 installations that require the filesystem, since an upgrade from SPIFFS to LittleFS is required, see munet Readme for additional information.
• 0.2.2 (2020-09-27) Support for LittleFS as successor of ESP8266/ESP32 filesystem
• 0.2.1 (2019-09-19) Functional support for AVRs added (from project functional-avr by winterscar).

References

• ustd_functional.h is taken from project functional-avr by winterscar
• ustd and muwerk are derivatives and lightweight versions of Meisterwerk.