System Command Extensions

Command Extensions provide the ability to extend an Operating System's command set. The adjective commonly given to this software attribute is "extensible." MIRTOS is very extensible.

It allows any command sent to the its Command Processor to be intercepted and "preprocessed". Command Extensions can be disabled or enabled with a single bit, BIT_SM_SCRIPT in EEPROM BYTE EEbSystemMode. The FLASH address of the subroutine to call to service Command Extensions is specified using the EEfptrNRFCmdExts pointer WORD. Both of these are found in the same definition file, SystemEEPROM.Def, which names and describes how the Operating System uses the first 80 bytes of reserved EEPROM.

The System Command Extensions allow the command to be selectively inspected, augmented, discarded, replaced or otherwise handled before the Operating System has a opportunity to parse the command and take the predetermined action on that command.

When disabled or when the pointer does not point to valid FLASH address, the Operating System handles all commands in the default manner. When enabled and given a valid PROGRAM address, the Operating System calls that address to give the Extension Processing routine "first crack" at handling the command.

The Operating System has received a request to process a command, which has come from one of three sources:
* user serial input, from a terminal program, either typed or from a script,
* a command script, enbuffered by the Script Processor, or
* a radio message received from another node via its nRF radio link.

In the first case, the Operating System itself has handled the serial input buffering, has determined that the line is complete (i.e., the user has hit a Carriage Return) and is ready for the command to be processed. It then holds any further characters in its raw serial (likely USB) input buffer until the prior command has completed foreground processing.

In the second case, one or more text commands have previously been stored in EEPROM or FLASH memory, the Script Processor has been invoked, has determined that Command Processor is not already busy, has encounterd a command that is not part of its own command set, and has placed that command in the Parsing Buffer. The Script Processor then waits for the command to be processed by the Command Processor before it attempts to read another script command.

In the last case, the nRF Radio processor has received a command via the nRF Radio link after a successful login, has been determined that the command is not part of its own command set or the nRF extensions, and has placed the command in the Parsing Buffer. It does not check to see if the the System Command Processor was busy, since radio commands are not saved, are generally control commands, used when not interacting with a human operator.

Only the main Operating System routine actually calls the System Command Processor and does so in the Foreground. A Background process can be interrupted by the Foreground processor. It is not valid to assume that the serial Parsing Buffer is the buffer from which the command was sent to the Command Processor.

Passed:	R31:R30	WORD *	wPtrMyAddress	The ICALL address used to reach this subroutine
	R29:R28	BYTE *	bPtrUVars	pointer to *uVars.B[0]
	R27:R26	BYTE *	bPtrBuffer	pointer to the text buffer being parsed, formatted as: the buffered byte count in the first byte, then the ASCIIz text string (command buffer) follows it
	R23	CHAR	cBuffer3	third buffered character, uppercase (but may be 0)
	R22	CHAR	cBuffer2	second buffered character, uppercase (but may be 0)
	R21	CHAR	cCmdByte	first buffered character, uppercase; the command byte
	R20	BYTE	bStrlen	string length, or buffered byte count
	R19:R18	WORD *	wPtrHandler	the WORD address of that command's default handler
Returns:	FLAGS	ZERO	flag	TRUE if the command was NOT handled (so process as usual), or FALSE if it was handled (so skip the default processing)

Again, all the general register usage rules for all subroutines still apply and are (unless otherwise noted):
* R0 is a temporary "scratch" register; assume any called routine may have changed it,
* R1 should always contain the value zero (0), but may be used and restored, if needed,
* R2 through R17, R28 and R29 contain system variables; they also may be used but must be restored,
* R18 through R27, R30 and R31, like R0, may all be used without saving and restoring them.

Filename	Description	Notes
ExtBaseline.Asm	CE_Default	Default Command Extensions supplied with MIRTOS Version 3.01

There are a number of constant definition files to include at the beginning of your assembly language source code files. If not specified by numeric MCU in the name, each file below is for all three (3) supported MCUs. Consider including this block (some depend on the .INCLUDE order):

; All INCLUDE files should be in the same directory as this .ASM source code (or)
;  use the "-I" parameter to set the AVR-AS "Include" directory where they are located:
.INCLUDE "CommonDefs.Def"        ; TRUE, FALSE, YES, NO, BIT_PV_*, et.al.
.INCLUDE "BinDefs.Def"           ; The B0 to B11111111 definitions
.INCLUDE "Indices.Def"           ; All 128 indirectly-accessed system jump indices
.IF PROCESSOR == 328
   .INCLUDE "IOM328P.Def"        ; Register definitions for the ATmega328P
   .INCLUDE "Addresses328.Def"   ; All 128 328P system routines' Jump Table addresses
   .INCLUDE "SystemSRAM328.Def"  ; Names and addresses of 328P system SRAM variables
.ENDIF
.IF PROCESSOR == 1284
   .INCLUDE "IOM1284P.Def"       ; Register definitions for the ATmega1284P
   .INCLUDE "Addresses1284.Def"  ; All 128 1284P system routines' Jump Table addresses
   .INCLUDE "SystemSRAM1284.Def" ; Names and addresses of 1284P system SRAM variables
.ENDIF
.IF PROCESSOR == 2560
   .INCLUDE "IOM2560.Def"        ; Register definitions for the ATmega2560
   .INCLUDE "Addresses2560.Def"  ; All 128 2560 system routines' Jump Table addresses
   .INCLUDE "SystemSRAM2560.Def" ; Names and addresses of 2560 system SRAM variables
.ENDIF
.IFNDEF APushAllRegisters
   .ERROR "Exiting: definition files not pulled in."
.ENDIF
.INCLUDE "SystemEEPROM.Def"      ; Names and addresses of system EEPROM variables
.INCLUDE "SystemFLASH.Def"       ; Names and addresses of system FLASH constants
;
; Only include this last .DEF file if nRF24L01+ constants are needed:
.INCLUDE "nRF24L01.Def"          ; Register and variable names for nRF radio use

Also see:

Scripts and their extensions, nRF Radio commands and extensions, WS2812 command extensions.