TerSer/README.md

# TerSer

A much smaller and more efficient serial library than Arduinos Serial by [Didel](https://www.didel.com). 
Use one include file to replace the Serial.print from Arduino library.

**Table of Contents**  
[What is the problem with Arduino Serial.print ?](#what-is-the-problem-with-arduino-serialprint-)  
[How to switch from Arduino Serial](#howto-switch-from-arduino-serial)  
[Installation](#terser-installation)  
[TerSer Limitations](#terser-limitations)  
[Function reference](#function-reference)  
[About TerSer Library](#about-terser-library)  

### What is the problem with Arduino Serial.print ?
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.

The TerSer.h offer the choice of 4 print format for numbers. Signed variables have a + or – sign in front. 

| 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") |


### 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:
* Add  `#include <TerSer.h>` at the top of your sketch or select the library from your Arduino IDE (*Sketch* | *Include Library*)
* Use the either the library function names we provide or define your own function names, for example:
  `#define Serialprint(x) Serialprint(x)`
* 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)`  
`#define Serialprint(x,BIN) Bin8(x)`  
`#define Serialprint(x,BIN) Bin16(x)`  
`#define Serialprint(x) Dec16(x)`  
etc.

### TerSer Installation 
#### Install in Arduino Library Manager
* (not active yet!) *
Go to library manager in your Arduino IDE and search for 'TerSer'.
Use the following syntax to include:
`#include <TerSer.h>`

#### Install in Arduino IDE via 'ADD .ZIP Library'
Download a zip file of the git repo, i.e. from https://git.boxtec.ch/didel/TerSer/archive/master.zip  
Open Arduino IDE (>=1.6) and navigate to *Sketch | Include Library | Add .ZIP Library* and select the just downloaded zip file.  
You should now find the Library under *Sketch | Include Library* ready to select.

#### Install manually, portable with sketch
Alternatively just download the TerSer.h into your sketch folder and include it directly from your sketch folder with:  
`#include "TerSer.h"`


### TerSer Limitations
TerSer's `Get()` function is blocking, that means it will not return until a character has been received over serial and currently no timeout can be specified. 

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();

#### Baud rate
The baud rate is hardwired into TerSer.h and is by default set to 9600 bps. The serial speed is configured on the UBRR0 register. 

```void SetupTerSer() {
  UBRR0= 103;  //  9600 bits/s
  UCSR0B=0x18; // -- -- -- rxe txe -- -- --
  UCSR0C=0x06; // set mode: 8 data bits, no parity, 1 stop bit
```

If you need another baud rate than 9600 you can adjust the value in the TerSer.h according to the table below:

| Baud rate | UBRR0 register *(16MHz clock)* |
| ---------- | ---------- |
| 2400 | `UBRR0= 416;` |
| 4800 | `UBRR0= 207;` |
| **9600** | `UBRR0= 103;` *(default)* |
| 19200 | `UBRR0= 51;` |
| 38400 | `UBRR0= 25;` |
| 57600 | `UBRR0= 16;` |
| 115200 | `UBRR0= 6;` |

For more information please see the [ATmega328 Datasheet](http://ww1.microchip.com/downloads/en/DeviceDoc/ATmega48A-PA-88A-PA-168A-PA-328-P-DS-DS40002061A.pdf) *(page 182)*.


### Function reference
| TerSer function | Description | Example use |
| --------------- | --------------- | --------------- |
| `Car(cc);` | Send code cc to the UART | `Car(' '); Car(32);  Car(0x20);  //All three print a space` |
| `cc=Get();` | Wait for a key depressed. Use Teraterm, or other terminal software that does not work line-oriented. | `Car( Get() ); //Echo typed character` |
| `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) | `Bin8(33);  // Output: 00100001` |
| `Bin16(v);`	| Display the 16 bits of the variable v, with a dot in the middle | `Bin16(1035); // Output: 00000100.00001011` |
| `Hex8(v);` | Display the 2 nibbles of the variable v, converted to integers | `Hex8(33); // Output: 21` |
| `Hex16(v);` | Display the 4 nibbles of the variable v, converted to integers | `Hex16(1035); // Output: 040B` | 
| `Hex32(v);` | Display the 8 nibbles of the variable v, converted to integers | `Hex32(260); // Output: 00000104` |
| `Dec8(v);` | Display the variable v, with its signs if signed and non-significative space or zeros | `Dec8(33); // Output: +.33. or +033. or .+33` |
| `Dec16(v);` | Display the variable v, with its signs if signed and non-significative space or zeros | `Bin8(1035); // Output: +.1035. or +01035.  or .+1035` |
| `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 | |

See the included example code for practical usage of the TerSer library.

### About TerSer Library
The TerSer Library was written and is maintained by [Jean-Daniel Nicoud from Didel](https://www.didel.com/). The library package and git repo is maintained by [Boxtec](https://boxtec.ch).
If you have any questions or comments, please post in the [Boxtec Support Forum](https://forum.boxtec.ch).