New Capability: HSerPrintList

[Anobium]

A new way to optimise sending lots of serial instructions avaliable in build 1651.

Syntax:

HSerPrintList value1, value2 [, value3 ... ]
HSerPrintList [comport], value1, value2 [, value3 ... ]

Enabling Constants:

The same enabling constants as HSerPrint apply.

'USART settings for USART1
#define USART_BAUD_RATE 9600
#define USART_TX_BLOCKING
#define USART_DELAY OFF

Explanation:

HSerPrintList sends two or more values in a single statement, instead of writing one HSerPrint call per value. Each value can be a string, integer, long, word or byte, and each is sent using the matching typed HSerPrint call, in the order given, to the default comport. Because the compiler expands the list into ordinary HSerPrint calls, mixing types in one statement — a string, then a byte, then a word, and so on — works exactly as if each value had been sent with its own HSerPrint statement.

HSerPrintList does not send any new line characters. As with HSerPrint, follow the statement with HSerPrint 13 and HSerPrint 10 if the receiving terminal needs a new line.

An optional leading [comport] argument sends every value in the list to that comport instead of the default. comport must be a number or a defined constant, and a comma must follow the closing ] - HSerPrintList [2] a, b (no comma) is rejected with a compile error rather than silently accepted. Internally this passes the comport straight through to HSerPrint’s own existing comport parameter on each expanded call (HSerPrint value, comport), so HSerPrintList [2], a, b is exactly equivalent to writing HSerPrint a, 2 and HSerPrint b, 2 by long hand. This type comport argument is not available on Ser1PrintList, Ser2PrintList or Ser3PrintList, since a software-serial channel has no comport to select.

Note

The compiler merges a repeated, identical comport setup across consecutive expanded calls, so HSerPrintList [2], a, b, c only sets the comport once in the generated code rather than once per value (PIC and AVR both). This optimisation is automatically disabled for the whole program if it defines an Interrupt sub, since an interrupt could otherwise fire between two calls and change the comport for its own purposes without the compiler being able to see that from this code alone.

Example:

#chip 16F877A, 20

#define USART_BAUD_RATE 9600
#define USART_TX_BLOCKING
#define USART_DELAY OFF

Dim Txt_Heading As String * 12 = "Send North"
Dim SignalLevel As Byte = 87
Dim SampleCount As Word = 4213

Do
  HSerPrintList "{STAT,", Txt_Heading, ",", SignalLevel, ",", SampleCount, "}", 13, 10   ' <<< the HSerPrintList instruction
  Wait 1 s
Loop

Key line: the single HSerPrintList call above sends a string literal, a string variable, another string literal, a byte, another string literal, a word, a closing brace and a CR/LF pair — nine values in total — as nine typed HSerPrint calls, without writing any of them out by hand.

Example with a comport:

#chip 16F877A, 20

#define USART_BAUD_RATE 9600
#define USART_TX_BLOCKING
#define USART_DELAY OFF

#define MyPort 2

Dim SignalLevel As Byte = 87
Dim SampleCount As Word = 4213

Do
  HSerPrintList [MyPort], SignalLevel, ",", SampleCount, 13, 10   ' <<< sends to MyPort (2)
  Wait 1 s
Loop

Key line: every value in the HSerPrintList call is sent to comport 2 (via the MyPort constant), instead of the default comport.

[Anobium]

A really good example of the HSerPrintList capability.

#chip 16F877A, 20

#define USART_BAUD_RATE 9600
#define USART_TX_BLOCKING
#define USART_DELAY OFF

'Demonstrates side by side with the code it replaces: sending the same
'nine values to comport 2, once the old long way (one HSerPrint call per value,
'each with its own explicit comport argument) and once the new way (a single
'HSerPrintList [2], ... statement). Both Subs below send byte-for-byte identical
'output - the difference is only how much of it you have to type and maintain.

Dim Txt_Heading As String * 12 = "Send North"
Dim SignalLevel As Byte = 87
Dim SampleCount As Word = 4213

Sub OldWay
  'The long way: one HSerPrint call per value, each one
  'repeating the same comport argument by hand. Nine values, nine statements.
  HSerPrint "{STAT,", 2
  HSerPrint Txt_Heading, 2
  HSerPrint ",", 2
  HSerPrint SignalLevel, 2
  HSerPrint ",", 2
  HSerPrint SampleCount, 2
  HSerPrint "}", 2
  HSerPrint 13, 2
  HSerPrint 10, 2
End Sub

Sub NewWay
  'The new way: the same nine values and the same comport, but as
  'one statement - the compiler expands this into the same nine HSerPrint calls
  'shown in OldWay above.
  HSerPrintList [2], "{STAT,", Txt_Heading, ",", SignalLevel, ",", SampleCount, "}", 13, 10
End Sub

Do
  OldWay
  NewWay
  Wait 1 s
Loop