From Ethersex_Wiki
Revision as of 19:29, 27 March 2012 by Mgue (talk | contribs) (first version)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

For general information on ECMD, see ECMD.

The following variables will be used on this page. Replace them for your module.

  • COMMAND - how the command will be invoked
  • ARGUMENT1...ARGUMENTN - the arguments that will be passed together with COMMAND
  • FUNCTIONNAME - the name of the function which will handle the command
  • MODULENAME - the name of the module


  • Create a new file inside the folder of the module MODULENAME_ecmd.c
  • Add this file to the Makefile of the module.
  • Open the file and "#include "protocols/ecmd/ecmd-base.h" and other necessary headers.
  • Add the header of the module, <string.h> etc.

Create a new command

Start with the following template:

int16_t parse_cmd_FUNCTIONNAME (char *cmd, char *output, uint16_t len)
        /* Your Code here */
	return ECMD_FINAL_OK;

Whenever COMMAND is invoked, this function will be called to handle it.


  • *cmd holds ARGUMENT1...ARGUMENTN which have been passed along with the command
  • len is the length of the command (*cmd). Use this for securely parsing *cmd.
  • *output is the output buffer which can hold 50 bytes/characters

Return values

ECMD_FINAL_OK the command has been executed without any errors. "OK" will be written to the caller's output.
ECMD_FINAL(len) the command has been executed. len bytes of *output will be written to the caller's output
ECMD_AGAIN(len) the command has been executed but needs to be called again. len bytes of *output will be written to the caller's output
ECMD_ERR_PARSE_ERROR the command couldn't be executed (missing/wrong arguments etc.)
ECMD_ERR_READ_ERROR the command couldn't be executed (not able to read from device/hardware)
ECMD_ERR_WRITE_ERROR the command couldn't be executed (not able to write to device/hardware)

Announce the command

Append this to the bottom of MODULENAME_ecmd.c to let the ECMD parser know about the new command.

-- Ethersex META --

The COMMAND along with the arguments and the description will show up here

Tips and best practice

Recursive calling a command handler function

If you need to output a lot of data (>50 bytes) , you need to recursivly call the command handler function using ECMD_AGAIN().

Instead of using unsafe static variables to keep track of the current progress you can use the following code:

 /* trick: use bytes on cmd as "connection specific static variables" */
    if (cmd[0] != 23) {		/* indicator flag: real invocation:  0 */
	cmd[0] = 23;		/*                 continuing call: 23 */
	cmd[1] = 0;		/* local variable 1 */

source example