alex/GY-63_MS5611
1
0
Fork 0
mirror of https://github.com/RobTillaart/Arduino.git synced 2024-10-03 18:09:02 -04:00
Code Issues Actions Packages Projects Releases Wiki Activity
f2e0254ab3
GY-63_MS5611/libraries/SHEX/README.md
rob tillaart f2e0254ab3 0.3.1 SHEX
2022-11-24 12:47:19 +01:00

5.4 KiB
Raw Blame History

Arduino CI Arduino-lint JSON check License: MIT GitHub release

SHEX

Arduino library to generate hex dump over Serial (any stream).

Description

SHEX

SHEX is a simple library that wraps the Serial output side (by default) and generates an hex dump of all data that is printed. 16 bytes per row.

The default output format is (changed since 0.3.0)

ABCD  xx xx xx xx  xx xx xx xx  xx xx xx xx  xx xx xx xx
ABCD  xx xx xx xx  xx xx xx xx  xx xx xx xx  xx xx xx xx
ABCD  xx xx xx xx  xx xx xx xx  xx xx xx xx  xx xx xx xx

ABCD  xx xx xx xx  xx xx xx xx  xx xx xx xx  xx xx xx xx

with a separator line after each 8th line.

The constructor has a length parameter which can be used to have another number of bytes per row. This can be changed with setBytesPerLine().

One can toggle is HEX output or pass through by means of setHEX(bool). This makes it possible to switch between the modes e.g. between 'debugging' and 'release' mode.

One can toggle the character count at the start of the line.

SHEXA

SHEXA (Serial HEX Ascii) is a derived class from SHEX that also displays a column with printable characters.

The default output format is

ABCD  xx xx xx xx  xx xx xx xx  xx xx xx xx  xx xx xx xx  abcdefgh ijklmnop
ABCD  xx xx xx xx  xx xx xx xx  xx xx xx xx  xx xx xx xx  abcdefgh ijklmnop
ABCD  xx xx xx xx  xx xx xx xx  xx xx xx xx  xx xx xx xx  abcdefgh ijklmnop

ABCD  xx xx xx xx  xx xx xx xx  xx xx xx xx  xx xx xx xx

To print this ASCII column extra RAM and code is used. Therefore this is made a derived class from SHEX.

Furthermore SHEXA has a function flushASCII() to flush the ASCII column to output. This is might be needed when HEX output is restarted.

Interface

The SHEX and SHEXA share most of their interface.

Defines

To be adjusted via command line (or in SHEX.h file)

  • SHEX_DEFAULT_LENGTH 16
  • SHEX_MAX_LENGTH 32
  • SHEX_MIN_LENGTH 4
  • SHEX_COUNTER_DIGITS 4
  • SHEX_DEFAULT_VTAB 8

Constructor + Core

  • SHEX(Print * stream = &Serial, uint8_t length = SHEX_DEFAULT_LENGTH) Constructor, optional set the number of bytes per line. default 16 bytes per line, forced multiple of 4, max SHEX_MAX_LENGTH = 32.
  • size_t write(uint8_t c) implements the Print interface.

Output Modifiers

  • void setHEX(bool hexOutput = true) switch between modi, HEX (true) or pass through (false).
  • bool getHEX() returns mode set above.
  • void setBytesPerLine(uint8_t length = SHEX_DEFAULT_LENGTH) idem, default 16 bytes per line, forced multiple of 4, max SHEX_MAX_LENGTH = 32.
  • uint8_t getBytesPerLine() returns number of bytes per line.

Separator

  • void setSeparator(char c = ' ') set the separator character, default a space. Some people like a dot '.', or a tab '\t'. Feel free to experiment.
  • char getSeparator() return the separator character set.

Counter

  • void setCountDigits(uint8_t digits) set the length of the counter, 8 or 6 or 4 (default). Other numbers will be rounded up to 4, 6 or 8.
  • uint8_t getCountDigits() returns idem.
  • void restartOutput() restarts the counter from 0 and a new line. Is automatically called if a setting is modified like bytesPerLine setVTAB or setCountDigits
  • uint32_t getCounter() return internal counter.

VTAB

  • void setVTAB(uint8_t vtab = SHEX_DEFAULT_VTAB) set the vertical separator line.
  • uint8_t getVTAB() return the current vertical separator line.

SHEXA specific

  • void flushASCII() allows the user to flush the ASCII column to output. This is typically used after a setting is changed, which causes a restart of the HEX output. Best if followed by a restartOutput(). Note: it is not ideal but workable. This might change in the future.

Operational

See examples.

Future

Although no follow up release is planned, some ideas are kept here so they won't get lost.

Must

  • optimize code
    • print vs write

should

  • more testing
    • performance measurement
    • different platforms.
    • different streams incl SW Serial

Could

  • investigate flushASCII() for better solutions.
  • HEX reader: RHEX converts dump format to a normal stream again.
    • separate library.
  • void setSeparatorInterval() ??

Wont

  • line buffering for faster output (e.g Ethernet and SD card) could it support write(array, length) call. needs quite a rewrite.. Needs a big buffer: ~150 bytes. (counter 8 + hex 96 + printable 32 + extra sep) ==> go through a small buffer twice as data is same!!
  • header line: runtime configurable; optional combined with separator and after how many lines the header should repeat header(str, lines) ? Can also be done by just calling Serial.print.