You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

127 lines
7.1 KiB

6 years ago
# TerSer
6 years ago
A much smaller and more efficient serial library than Arduinos Serial by [Didel](https://www.didel.com).
6 years ago
Use one include file to replace the Serial.print from Arduino library.
6 years ago
6 years ago
**Table of Contents**
6 years ago
[What is the problem with Arduino Serial.print ?](#what-is-the-problem-with-arduino-serialprint-)
[Example comparison between Didel TerSer and Arduino Serial](#example-comparison-between-didel-terser-and-arduino-serial)
[Using tabular data](#using-tabular-data)
6 years ago
[How to switch from Arduino Serial](#howto-switch-from-arduino-serial)
[Installation](#terser-installation)
[Using tabular data](#using-tabular-data)
6 years ago
[TerSer Limitations](#terser-limitations)
[Code size and timing comparison](#code-size-and-timing-comparison)
6 years ago
[Function reference](#function-reference)
6 years ago
### What is the problem with Arduino Serial.print ?
6 years ago
Serial.print is is most of the time used as a debugging tool, and with limited resources it is even more important to have the most lighweight solution for this task.
Also when Serial debugging is used to display sensor values, as shown next, suppressing non significative zeros is not adequate for tabular data, specially when the screen is scrolling.
Serial.print is a good example of the "Law of instrument":
One just uses a bad but widely available tool, and is not willing to find or invent a better one.
We propose to use a compact C portable library. Compatibility with an Oled display is a further plus. The SerTerm.h and OledTerm.h are demonstrated on the popular Arduino environment, but it is just plain C.
It is admittedly very convenient to just use Serial.print(var); since it doesn't require you to specify the type of variable. Though when trying for example to output data in tabular style the processor needs to know the data type used so that it can reserve the adequate space for it in its output. It might seem like a big inconvenience to specify the data type with any statement that outputs data over serial but then again for debugging purposes it makes perfectly sense in terms of speed AND size of the resulting code. By the same reasons we also do not use a buffer as it is needed only in specific situations.
6 years ago
6 years ago
The TerSer.h offer the choice of 4 print format for numbers. Signed variables have a + or sign in front.
6 years ago
6 years ago
| Normal (moz=0) | Spaces (moz=1) | Zeros (moz=2) | Compact (moz=3) | Serial.print |
| -------------- | -------------- | -------------- | -------------- | -------------- |
| ![moz0](docs/images/tab_moz0.png?raw=true "Example moz=0") | ![moz1](docs/images/tab_moz1.png?raw=true "Example moz=1") | ![moz2](docs/images/tab_moz2.png?raw=true "Example moz=2") | ![moz3](docs/images/tab_moz3.png?raw=true "Example moz=3") | ![Aserial](docs/images/tab_arduino_serial.png?raw=true "Example Arduino Serial.print") |
6 years ago
6 years ago
### How to switch from Arduino Serial
If you are looking for a drop-in replacement for Arduino Serial with a smaller memory footprint follow the procedure outlined below to quickly switch your project to Didel TerSer:
6 years ago
* Add `#include <TerSer.h>` at the top of your sketch or select the library from your Arduino IDE (*Sketch* | *Include Library*)
6 years ago
* Use the either the library function names we provide or define your own function names, for example:
6 years ago
`#define Serialprint(x) Text(x)`
6 years ago
* Search for all occurences or `Serial.print` and replace with `Serialprint`
Voila, you have switched to TerSer and enjoy smaller footprint at less mcu cycles
#### Function aliasing
If you do not like our function/method names, feel free to define names that suit your tastes with i.e.:
`#define Serialprint(x) Text(x)`
6 years ago
6 years ago
`#define Serialprint(x,BIN) Bin8(x)`
6 years ago
6 years ago
`#define Serialprint(x,BIN) Bin16(x)`
6 years ago
6 years ago
`#define Serialprint(x) Dec16(x)`
6 years ago
6 years ago
etc.
### TerSer Installation
6 years ago
Go to library manager in your Arduino IDE and search for 'TerSer'.
6 years ago
6 years ago
### Example comparison between Didel TerSer and Arduino Serial
6 years ago
| TerSer | Output TerSer | Output Serial | Arduino Serial |
| ------------- | ------------- | ------------- | ------------- |
| Car('Z'); | Z | Z | Serial.print('Z'); |
| Text("Test"); | Test | Test | Serial.print("Test"); |
| Bin16(v16); | 0000010001100000 | 10001100000 | Serial.print(v16,BIN); |
| Hex16(v16); | 08c0 | 8c0 | Serial.print(v16,HEX); |
| Dec16(v16); | 1120 | 1120 | Serial.print(v16); |
| Dec16(v16b); | 0020 or 20 | 20 | Serial.print(v16b); |
| Dec16(v16s); | + 20 or +0020 | 20 | Serial.print(v16s); |
| Dec16(-v16s); | 20 or -0020 | -20 | Serial.print(-v16s); |
6 years ago
*uint16_t v16=1120; uint16_t v16b=20; int16_t v16s=20;*
6 years ago
6 years ago
### Using tabular data
6 years ago
Filling the non significative digits with zero or space is a general options, named ShowZ(); and HideZ();
The Tab(nn); function, allows to align data of different types.
e.g. Table next had to be written:
Text ("Mode HideZ();") SetTab(15);
Text ("Mode ShowZ();");NL();
HideZ();Dec8s(3); SetTab(15);
ShowZ();Dec8s(3); NL();
. . .
6 years ago
![Table1](docs/images/tabTable.png?raw=true "Example Table 1")
6 years ago
It is up to you to add functions like TextNL();
if you need to keep your Serial.println() habits.
6 years ago
6 years ago
6 years ago
### TerSer Limitations
TerSer does not print floating point numbers.
The may happen some day with one more file to import, e.g. names TerFloat.h.
Dec8(); and Dec16(); use a tricky macro to recognize the signed or unsigned data type. The parameter must be a single variable, e.g. Dec8(var); Dec8(var+2); will give wrong results.
Code will be shorter and there will be no limitation if you use Dec8u(any unsigned expr); and
Dec8s(any signed expr);, same of course Dec16u(); and Dec16s();
### Code size and timing comparison
Code size has been obtained by calling one function at a time, compiler under the usual -0s mode. Size is the difference with the empty file size. TerSer.h can of course be used with setup() and loop(). It add the ~300 bytes Arduino initializations.
Execution time has been measured with a Nop replacing the SendCar function. The time depends on the baud rate, ~1 ms per character displayed at 9600 bits/s.
6 years ago
### Function reference
| TerSer function | |
| --------------- | --------------- |
| Car(cc); | Send code cc to the UART |
| cc=Get(); | Wait for a key depressed. Use Teraterm, too tricky with Arduino Terminal |
| Text("abcd"); | Send the text and add a space |
|Textln("abcd"); | Same with CRLF |
| CR(); | Send a CR-LF |
| Bin8(v); | Display the 8 low bits of the variable v, converted to integers (all add a space) |
| Bin16(v); | Display the 16 bits of the variable v, with a dot in the middle |
| Hex8(v); | Display the 2 nibbles of the variable v, converted to integers |
| Hex16(v); | Display the 4 nibbles of the variable v, converted to integers |
| Hex32(v); | Display the 8 nibbles of the variable v, converted to integers |
| Dec8(v); | Display the variable v, with its signs if signed and non-significative space or zeros |
| Dec16(v); | Display the variable v, with its signs if signed and non-significative space or zeros |
| Dec8u(unsigned); Dec8s(signed); | Shorter code |
| Dec16u(unsigned); Dec16s(signed); | Shorter code |
| Normal(); | ..+nnn default mode (a dot represents a space) |
| Spaces(); | +..nnn best for tabular data |
| Zeros(); | +00nnn if you prefer |
| Compact(); | +nnn same as Arduino, but a + is shown if positive signed variable |
6 years ago