From 6d60974c893692faa9d98a54939b947b10ac9d76 Mon Sep 17 00:00:00 2001 From: rob tillaart Date: Tue, 31 Jan 2023 20:16:44 +0100 Subject: [PATCH] 0.1.8 ANSI --- .../ANSI/.github/workflows/arduino-lint.yml | 2 +- .../.github/workflows/arduino_test_runner.yml | 2 +- .../ANSI/.github/workflows/jsoncheck.yml | 2 +- libraries/ANSI/CHANGELOG.md | 17 ++- libraries/ANSI/LICENSE | 2 +- libraries/ANSI/README.md | 116 ++++++++++++--- libraries/ANSI/ansi.cpp | 26 ++-- libraries/ANSI/ansi.h | 51 ++++--- .../ansi_132_column/ansi_132_column.ino | 69 +++++++++ .../ansi_char_test/ansi_char_test.ino | 2 - .../ANSI/examples/ansi_clock/ansi_clock.ino | 139 ++++++++++++++++++ libraries/ANSI/keywords.txt | 9 ++ libraries/ANSI/library.json | 4 +- libraries/ANSI/library.properties | 6 +- libraries/ANSI/test/unit_test_001.cpp | 2 +- 15 files changed, 386 insertions(+), 63 deletions(-) create mode 100644 libraries/ANSI/examples/ansi_132_column/ansi_132_column.ino create mode 100644 libraries/ANSI/examples/ansi_clock/ansi_clock.ino diff --git a/libraries/ANSI/.github/workflows/arduino-lint.yml b/libraries/ANSI/.github/workflows/arduino-lint.yml index b2ca058c1..8a26f14a5 100644 --- a/libraries/ANSI/.github/workflows/arduino-lint.yml +++ b/libraries/ANSI/.github/workflows/arduino-lint.yml @@ -6,7 +6,7 @@ jobs: lint: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - uses: arduino/arduino-lint-action@v1 with: library-manager: update diff --git a/libraries/ANSI/.github/workflows/arduino_test_runner.yml b/libraries/ANSI/.github/workflows/arduino_test_runner.yml index 096b975b3..fadfa9043 100644 --- a/libraries/ANSI/.github/workflows/arduino_test_runner.yml +++ b/libraries/ANSI/.github/workflows/arduino_test_runner.yml @@ -8,7 +8,7 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - uses: ruby/setup-ruby@v1 with: ruby-version: 2.6 diff --git a/libraries/ANSI/.github/workflows/jsoncheck.yml b/libraries/ANSI/.github/workflows/jsoncheck.yml index 04603d081..37a11298c 100644 --- a/libraries/ANSI/.github/workflows/jsoncheck.yml +++ b/libraries/ANSI/.github/workflows/jsoncheck.yml @@ -10,7 +10,7 @@ jobs: test: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - name: json-syntax-check uses: limitusus/json-syntax-check@v1 with: diff --git a/libraries/ANSI/CHANGELOG.md b/libraries/ANSI/CHANGELOG.md index 8b2824fb1..5f3f48286 100644 --- a/libraries/ANSI/CHANGELOG.md +++ b/libraries/ANSI/CHANGELOG.md @@ -6,13 +6,22 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this project adheres to [Semantic Versioning](http://semver.org/). -## [0.1.7] - 2022-110-28 +## [0.1.8] - 2023-01-31 +- update readme.md +- update GitHub actions +- update license 2023 +- minor edit unit test +- add example ansi_clock.ino +- add example ansi_132_columns.ino +- minor edits + + +## [0.1.7] - 2022-10-28 - add RP2040 to build-CI - minor edits - start simplifying changelog - minor change unit test - ## [0.1.6] - 2022-04-11 - add CHANGELOG.md - add **int deviceType()** @@ -37,9 +46,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/). ## [0.1.1] - 2020-05-27 - update library.json - ## [0.1.0] - 2020-04-28 - initial release - + Based upon my VT100 library (from 2013) which is now obsolete. + This vt100 lib had just a list of escape sequences #defined. diff --git a/libraries/ANSI/LICENSE b/libraries/ANSI/LICENSE index c3d6b3da5..42604f343 100644 --- a/libraries/ANSI/LICENSE +++ b/libraries/ANSI/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2020-2022 Rob Tillaart +Copyright (c) 2020-2023 Rob Tillaart Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/libraries/ANSI/README.md b/libraries/ANSI/README.md index 6b06be5d8..307456075 100644 --- a/libraries/ANSI/README.md +++ b/libraries/ANSI/README.md @@ -13,11 +13,10 @@ Arduino library with basic ANSI display codes for terminal applications. # Description -ANSI codes are special codes that are send to a terminal e.g. VT100 to add -attributes to displayed characters. -Typical examples are bold, blink or colour. -Also known as escape codes the set of codes is large, however not -all terminal types do support all codes. +ANSI codes are special codes that are send to a terminal e.g. VT100 to add +attributes to displayed characters. +Typical examples are bold, blink or colour. ANSI codes are also known as escape codes. +The set of codes is large, however not all terminal types do support all codes. Sending these ANSI codes to a simple ASCII only terminal like the one in the Arduino IDE might result in garbage. So use with care. @@ -25,9 +24,9 @@ IDE might result in garbage. So use with care. ## Terminals tested -Tests are done with +Tests are done with - TeraTerm 4.102 + 4.106 (VT100, VT202, VT525 mode) -- Putty 0.71 +- Putty 0.71 Other terminal program's exist so please let me know if yours is working too. If not, please open an issue. @@ -38,33 +37,114 @@ If not, please open an issue. See examples -## Performance +## Interface + +```cpp +#include "ansi.h" +``` + +#### Constructor + +- **ANSI(Stream \* stream = &Serial)** wrapper around Serial. +Can be a software serial too. + + +#### Stream interface + +- **int available()** +- **int read()** +- **int peek()** +- **void flush()** + +Stream interface also includes print(), println(), write(). + + +#### Character modi + +- **void normal()** idem. +- **void bold()** idem. +- **void low()** idem. +- **void underline()** idem. +- **void blink()** idem. +- **void reverse()** idem. + + +#### Colour + +- **void foreground(uint8_t fgcolor)** +- **void background(uint8_t bgcolor)** +- **void color(uint8_t fgcolor, uint8_t bgcolor)** +- **uint8_t gray2color(uint8_t gray)** +- **uint8_t grey2color(uint8_t grey)** idem +- **uint8_t rgb2color(uint8_t r, uint8_t g, uint8_t b)** + + +todo colour table -Since 0.1.5 there is some focus on performance. -Using **ansi.print()** and **ansi.println()** for printing text and numbers is -improved a bit since 0.1.4 by adding the private **write(array, length)**. +#### Positioning -## Experimental 0.1.6 +- **void clearScreen()** +- **void clearLine(uint8_t clear = toEnd)** toEnd = 0, + toStart = 1,en tireLine = 2, +- **void home()** go to 0,0 +- **void gotoXY(uint8_t x, uint8_t y)** +- **void cursorUp(uint8_t x)** +- **void cursorDown(uint8_t x)** +- **void cursorForward(uint8_t x)** +- **void cursorBack(uint8_t x)** + + +#### Experimental + +look into **ansi.h** for experimental functions and notes. Version 0.1.6 added a number of experimental function that need more testing. -Some are working, others are unclear, but the user can uncomment these and -experiment with them if needed. +Some are working with Teraterm, others are unclear of fail. +The user can uncomment these and verify if these work with their terminal. -Also added is the **int deviceType()** function which also need more testing +Also added is the **int deviceType()** function which also need more testing. As always, constructive feedback is welcome. +## Performance + +Since 0.1.5 there is some focus on performance. +Using **ansi.print()** and **ansi.println()** for printing text and numbers is +improved a bit since 0.1.4 by adding the private **write(array, length)**. + + ## Future +#### Must + +- improve documentation + - elaborate interface + - colour info + +#### Should + +- test experimental functions - test more terminal programs (Linux mac) -- write more examples +- add examples - DOS emulator? + - experimental section + +#### Could + - increase functionality - - which codes are useful ? -- investigate performance. (first step made in 0.1.5 but more possible) + - which codes are generic / useful ? +- investigate performance. + - first step made in 0.1.5 but more possible - add line buffer in write(c) to improve throughput? - need for flush() with line buffer? - rewrite functions, replace print() by **\_stream->write()** calls? (effect on size?) + - move static strings to PROGMEM? as defines? + roughly ~20 bytes progmem for 4 bytes RAM... + - print(char) iso print(string) where possible + + +#### Wont + diff --git a/libraries/ANSI/ansi.cpp b/libraries/ANSI/ansi.cpp index 4e962d856..1e19ffa91 100644 --- a/libraries/ANSI/ansi.cpp +++ b/libraries/ANSI/ansi.cpp @@ -1,12 +1,10 @@ // // FILE: ansi.cpp // AUTHOR: Rob Tillaart -// VERSION: 0.1.7 +// VERSION: 0.1.8 // PURPOSE: Arduino library to send ANSI escape sequences // DATE: 2020-04-28 // URL: https://github.com/RobTillaart/ANSI -// -// HISTORY: See CHANGELOG.md #include "ansi.h" @@ -37,6 +35,7 @@ int ANSI::peek() void ANSI::clearScreen() { + // print(F("\033[2J\033[H")); print("\033[2J"); home(); } @@ -50,6 +49,13 @@ void ANSI::clearLine(uint8_t clear) } +void ANSI::home() +{ + print("\033[H"); +}; + + + // ANSI has three different color spaces: 4-bit color, 8-bit color, and 24-bit color // These are rendered with SGR 30-37,90-97/40-47,100-107, SGR 38;5/48;5, and SGR 38;2/48;2, respectively // The 4-bit color space is the most widely compatible and the most compactly transmitted @@ -97,8 +103,8 @@ void ANSI::color(uint8_t fgcolor, uint8_t bgcolor) uint8_t ANSI::rgb2color(uint8_t r, uint8_t g, uint8_t b) { return 16 + - 36 * (uint16_t(r) * 6 / 256) + - 6 * (uint16_t(g) * 6 / 256) + + 36 * (uint16_t(r) * 6 / 256) + + 6 * (uint16_t(g) * 6 / 256) + (uint16_t(b) * 6 / 256); } @@ -149,7 +155,7 @@ int ANSI::deviceType(uint32_t timeout) { int type = -1; // -1 = unknown print("\033[0c"); - + uint32_t start = millis(); int read_len = 0; char buffer[8]; @@ -161,8 +167,8 @@ int ANSI::deviceType(uint32_t timeout) { type = buffer[2] - '0'; } - // Serial.write(buffer, 3); - // Serial.println(); + // Serial.write(buffer, 3); + // Serial.println(); } return type; } @@ -174,7 +180,7 @@ int ANSI::deviceType(uint32_t timeout) // size_t ANSI::write(uint8_t c) { - // TODO add line buffer? - interference with write(array, length) !? + // add line buffer? - interference with write(array, length) !? return _stream->write(c); } @@ -222,5 +228,5 @@ void ANSI::color8(uint8_t base, uint8_t color) { } -// -- END OF FILE -- +// -- END OF FILE -- diff --git a/libraries/ANSI/ansi.h b/libraries/ANSI/ansi.h index efe3c9272..08cabe949 100644 --- a/libraries/ANSI/ansi.h +++ b/libraries/ANSI/ansi.h @@ -2,16 +2,15 @@ // // FILE: ansi.h // AUTHOR: Rob Tillaart -// VERSION: 0.1.7 +// VERSION: 0.1.8 // PURPOSE: Arduino library to send ANSI escape sequences // DATE: 2020-04-28 // URL: https://github.com/RobTillaart/ANSI -// #include "Arduino.h" -#define ANSI_LIB_VERSION (F("0.1.7")) +#define ANSI_LIB_VERSION (F("0.1.8")) class ANSI : public Stream @@ -58,7 +57,8 @@ class ANSI : public Stream void foreground(uint8_t fgcolor); // Set background color void background(uint8_t bgcolor); - // Set foreground and background color + + // Set foreground and background color // (for named colors, this is 25% faster than setting one then the other) void color(uint8_t fgcolor, uint8_t bgcolor); @@ -66,6 +66,7 @@ class ANSI : public Stream // Pass in a gray level from 0 (black) to 255 (white) uint8_t gray2color(uint8_t gray) { return 232 + uint16_t(gray) * 24 / 256; } uint8_t grey2color(uint8_t grey) { return this->gray2color(grey); } + // Convert RGB color to ANSI color in 4-bit colorspace // Pass in a RGB level from 0 (dark) to 255 (light) uint8_t rgb2color(uint8_t r, uint8_t g, uint8_t b); @@ -81,7 +82,7 @@ class ANSI : public Stream void clearScreen(); void clearLine(uint8_t clear = toEnd); - void home() { print("\033[H"); }; + void home(); void gotoXY(uint8_t x, uint8_t y); void cursorUp(uint8_t x); @@ -91,43 +92,55 @@ class ANSI : public Stream // META - // deviceType is discussed + // deviceType is discussed // - https://github.com/RobTillaart/ANSI/issues/9 - // timeout in milliseconds. + // timeout in milliseconds. // note this function blocks for timeout or less. - // -1 = unknown; + // -1 = unknown; // 1 = VT52, 2 = VT100, 3 = VT220, int deviceType(uint32_t timeout = 100); // EXPERIMENTAL SECTION // use at own risk - // check if it works on your terminal Tera + // check if it works on your terminal + // TERA + void set132columns() { print("\033[?3h"); }; // + + void set80columns() { print("\033[?3l"); }; // + + + void moveWindowDown() { print("\033M"); }; // + + void moveWindowUp() { print("\033D"); }; // + + + // PRINTING + void printScreen() { print("\033[i"); }; // + + + // RESET terminal to initial state + void reset() { print("\033c"); }; // + + + + // NOT working on TERA TERM (or need testing) + // use at own risk + // check if it works on your terminal TERA /* - void set132() { print("\033[?3h"); }; // + - void set80() { print("\033[?3l"); }; // + void setSmoothScroll() { print("\033[?4h"); }; // - void setJumpScroll() { print("\033[?4l"); }; // - - void moveWindowDown() { print("\033M"); }; // + - void moveWindowUp() { print("\033D"); }; // + + // to be used for password? void invisible() { print("\033[8m"); }; // - // PRINTING // use at own risk - // check if it works on your terminal Tera - void printScreen() { print("\033[i"); }; // + + // check if it works on your terminal TERA void printLine() { print("\033[1i"); }; // ? void startPrintLog() { print("\033[4i"); }; // ? void stopPrintLog() { print("\033[5i"); }; // ? - - // Reset terminal to initial state - void reset() { print("\033c"); }; // + */ + private: size_t write(uint8_t c); size_t write(uint8_t * array, uint8_t length); + void color4(uint8_t base, uint8_t color); void color4_code(uint8_t base, uint8_t color); void colors4(uint8_t fgcolor, uint8_t bgcolor); @@ -138,5 +151,5 @@ class ANSI : public Stream }; -// -- END OF FILE -- +// -- END OF FILE -- diff --git a/libraries/ANSI/examples/ansi_132_column/ansi_132_column.ino b/libraries/ANSI/examples/ansi_132_column/ansi_132_column.ino new file mode 100644 index 000000000..ee75b05fd --- /dev/null +++ b/libraries/ANSI/examples/ansi_132_column/ansi_132_column.ino @@ -0,0 +1,69 @@ +// +// FILE: ansi_132_column.ino +// AUTHOR: Rob Tillaart +// PURPOSE: demo clock +// URL: https://github.com/RobTillaart/ANSI +// (c) : MIT +// +// use Tera Term to view 132 columns. + + +char lorem[] = "Lorem ipsum dolor sit amet, \ +consectetuer adipiscing elit. Aenean commodo ligula eget dolor. \ +Aenean massa. Cum sociis natoque penatibus et magnis dis parturient \ +montes, nascetur ridiculus mus. Donec quam felis, ultricies nec, \ +pellentesque eu, pretium quis, sem. Nulla consequat massa quis enim. \ +Donec pede justo, fringilla vel, aliquet nec, vulputate eget, arcu. \ +In enim justo, rhoncus ut, imperdiet a, venenatis vitae, justo. \ +Nullam dictum felis eu pede mollis pretium. Integer tincidunt. \ +Cras dapibus. Vivamus elementum semper nisi. \ +Aenean vulputate eleifend tellus. Aenean leo ligula, porttitor eu, \ +consequat vitae, eleifend ac, enim. Aliquam lorem ante, dapibus in, \ +viverra quis, feugiat a, tellus. Phasellus viverra nulla ut metus \ +varius laoreet. Quisque rutrum. Aenean imperdiet. Etiam ultricies \ +nisi vel augue. Curabitur ullamcorper ultricies nisi. Nam eget dui."; + + + +#include "ansi.h" + +ANSI ansi(&Serial); + + + +void setup() +{ + Serial.begin(115200); + + // SPLASH SCREEN + ansi.set80columns(); + ansi.clearScreen(); + ansi.gotoXY(8, 10); + ansi.bold(); + ansi.print("DEMO ANSI TERMINAL 132 COLUMN"); + ansi.normal(); + delay(3000); + ansi.clearScreen(); + + ansi.set132columns(); + ansi.println(lorem); + ansi.println(); + + delay(5000); + ansi.set80columns(); + ansi.println(lorem); + ansi.println(); + + delay(5000); + ansi.set132columns(); + ansi.println(lorem); + ansi.println(); +} + + +void loop() +{ +} + + +// -- END OF FILE -- diff --git a/libraries/ANSI/examples/ansi_char_test/ansi_char_test.ino b/libraries/ANSI/examples/ansi_char_test/ansi_char_test.ino index c1e26db37..278aab328 100644 --- a/libraries/ANSI/examples/ansi_char_test/ansi_char_test.ino +++ b/libraries/ANSI/examples/ansi_char_test/ansi_char_test.ino @@ -6,7 +6,6 @@ // DATE: 2021-10-18 // URL: https://github.com/RobTillaart/ANSI // (c) : MIT -// #include "ansi.h" @@ -38,4 +37,3 @@ void loop() // -- END OF FILE -- - diff --git a/libraries/ANSI/examples/ansi_clock/ansi_clock.ino b/libraries/ANSI/examples/ansi_clock/ansi_clock.ino new file mode 100644 index 000000000..def7bfb57 --- /dev/null +++ b/libraries/ANSI/examples/ansi_clock/ansi_clock.ino @@ -0,0 +1,139 @@ +// +// FILE: ansi_clock.ino +// AUTHOR: Rob Tillaart +// PURPOSE: demo clock +// URL: https://github.com/RobTillaart/ANSI +// (c) : MIT +// +// use Tera Term to view 'different' clocks. + +#include "ansi.h" + +ANSI ansi(&Serial); + +int hh = 0; +int mm = 0; +int ss = 0; + +void setup() +{ + Serial.begin(115200); + + // SPLASH SCREEN + ansi.clearScreen(); + ansi.gotoXY(8, 10); + ansi.bold(); + ansi.print("DEMO ANSI TERMINAL"); + ansi.normal(); + delay(3000); + ansi.clearScreen(); + + // uses compile time + sscanf(__TIME__, "%d:%d:%d", &hh, &mm, &ss); +} + + +void loop() +{ + update_time(); + display_time_1(); + display_time_2(); + display_time_3(); +} + + +void update_time() +{ + static uint32_t lastTime = 0; + uint32_t now = millis(); + if (now - lastTime >= 1000) + { + lastTime = now; + ss++; + if (ss == 60) + { + ss = 0; + mm++; + }; + if (mm == 60) + { + mm = 0; + hh++; + }; + if (hh == 24) + { + hh = 0; + }; + } +} + + +// displays time per second +void display_time_1() +{ + static uint32_t lastTime = 0; + uint32_t now = millis(); + if (now - lastTime >= 1000) + { + lastTime = now; + ansi.gotoXY(2, 10); + ansi.print("TIME: "); + ansi.gotoXY(2, 16); + if (hh < 10) ansi.print(0); + ansi.print(hh); + ansi.print(':'); + if (mm < 10) ansi.print(0); + ansi.print(mm); + ansi.print(':'); + if (ss < 10) ansi.print(0); + ansi.print(ss); + } +} + + +// updates time every 5 seconds +void display_time_2() +{ + static uint32_t lastTime = 0; + uint32_t now = millis(); + if (now - lastTime >= 1000 && (ss % 5 == 0)) + { + lastTime = now; + ansi.gotoXY(4, 10); + ansi.print("TIME: "); + ansi.gotoXY(4, 16); + if (hh < 10) ansi.print(0); + ansi.print(hh); + ansi.print(':'); + if (mm < 10) ansi.print(0); + ansi.print(mm); + ansi.print(':'); + if (ss < 10) ansi.print(0); + ansi.print(ss); + } +} + + +// displays hours and minutes and a blink ".:" per second. +void display_time_3() +{ + static uint32_t lastTime = 0; + uint32_t now = millis(); + if (now - lastTime >= 1000) + { + lastTime = now; + ansi.gotoXY(6, 10); + ansi.print("TIME: "); + ansi.gotoXY(6, 16); + if (hh < 10) ansi.print(0); + ansi.print(hh); + if (ss & 0x01) ansi.print(':'); + else ansi.print('.'); + if (mm < 10) ansi.print(0); + ansi.print(mm); + } +} + + + +// -- END OF FILE -- diff --git a/libraries/ANSI/keywords.txt b/libraries/ANSI/keywords.txt index 7a3a593fb..a84411f1a 100644 --- a/libraries/ANSI/keywords.txt +++ b/libraries/ANSI/keywords.txt @@ -34,6 +34,15 @@ rgb2color KEYWORD2 deviceType KEYWORD2 +# EXPERIMENTAL + +set132columns KEYWORD2 +set80columns KEYWORD2 +moveWindowDown KEYWORD2 +moveWindowUp KEYWORD2 +printScreen KEYWORD2 +reset KEYWORD2 + # Constants (LITERAL1) toEnd LITERAL1 diff --git a/libraries/ANSI/library.json b/libraries/ANSI/library.json index 316a34d54..38c13a229 100644 --- a/libraries/ANSI/library.json +++ b/libraries/ANSI/library.json @@ -1,7 +1,7 @@ { "name": "ANSI", "keywords": "VT100, Tera Term, putty, Terminal", - "description": "Arduino library to send ANSI escape sequences. Experimental.", + "description": "Arduino library to send ANSI escape sequences.", "authors": [ { @@ -15,7 +15,7 @@ "type": "git", "url": "https://github.com/RobTillaart/ANSI.git" }, - "version": "0.1.7", + "version": "0.1.8", "license": "MIT", "frameworks": "arduino", "platforms": "*", diff --git a/libraries/ANSI/library.properties b/libraries/ANSI/library.properties index 2a342ee59..2f43dece7 100644 --- a/libraries/ANSI/library.properties +++ b/libraries/ANSI/library.properties @@ -1,9 +1,9 @@ name=ANSI -version=0.1.7 +version=0.1.8 author=Rob Tillaart maintainer=Rob Tillaart -sentence=Arduino library to send ANSI escape sequences -paragraph=VT100, Tera Term +sentence=Arduino library to send ANSI escape sequences. +paragraph=VT100, Tera Term, putty, terminal category=Communication url=https://github.com/RobTillaart/ANSI architectures=* diff --git a/libraries/ANSI/test/unit_test_001.cpp b/libraries/ANSI/test/unit_test_001.cpp index 401f54cfa..7320e3db9 100644 --- a/libraries/ANSI/test/unit_test_001.cpp +++ b/libraries/ANSI/test/unit_test_001.cpp @@ -2,7 +2,7 @@ // FILE: unit_test_001.cpp // AUTHOR: Rob Tillaart // DATE: 2020-12-11 -// PURPOSE: unit tests for the SHT31 temperature and humidity sensor +// PURPOSE: unit tests for the Arduino ANSI library // https://github.com/RobTillaart/ANSI // https://github.com/Arduino-CI/arduino_ci/blob/master/REFERENCE.md //