ECMD

Was ist ECMD?

ECMD steht für Ethersex Command. ECMD ist ein einfaches, textbasiertes Protokoll mit dem mit einem Ethersex-System kommuniziert werden kann. Neben der Konfiguration des Ethersex Systems können auch die Hardware Schnittstellen angesprochen werden. Viele Module bieten ebenfalls ecmd Unterstützung an. Einen Überblick über die implementieren Befehle gibt die ECMD Reference.

ECMD Schnittstellen

Unter ECMD Protokolle kannst du nachlesen, wie dein ethersex mit ECMD angesprochen werden kann. Wenn du dein ethersex über Shell Scripte oder eigene Programme ansprechen möchtest, empfiehlt sich evtl. die libecmd (geschrieben in C) im contrib Ordner, welche alle ECMD Protokolle beherrscht.

Eigenen ECMD Befehl erstellen

Vorbereitung

1. Wechsel in den Ordner des Moduls, welches ein neues ECMD bekommen soll.
2. Erstelle eine Datei [modulname]_ecmd.c
3. Füge #include "protocols/ecmd/ecmd-base.h ein

Funktionen

Baue nun Funktionen mit einer Signatur wie die folgende Funktion hat:

int16_t parse_FUNCTIONSNAME (char *cmd, char *output, uint16_t len)
{
	zu_was();
	return ECMD_FINAL_OK;
}

ECMD_FINAL_OK bedeutet hier, das der Aufruf ein Erfolg war. Hierrauf wird im http Interface beispielsweise ein OK zurückgegeben. Wenn etwas schief läuft oder die Argumentanzahl falsch ist, dann kannst du ECMD_ERR_PARSE_ERROR zurückgeben. Wie läuft das eigentlich mit den ecmd Argumenten für dein neues Kommando? Hier siehst du ein kleines Beispiel um 3 Zahlen als Argumente entgegen zunehmen:

int16_t parse_FUNCTIONSNAME2 (char *cmd, char *output, uint16_t len)
{
	uint8_t val1=0;
	uint8_t val2=0;
	uint8_t val3 = 0;
	ret = sscanf_P(cmd, PSTR("%hhu %hhu %hhu"), &val1, &val2, &val3);
	if (ret == 3)
		return ECMD_FINAL_OK;
	else
		return ECMD_ERR_PARSE_ERROR;
}

Möchtest du auch andere Dinge als OK und PARSE ERROR zurückgeben können, nimmst du folgenden Code:

return ECMD_FINAL(snprintf_P(output, len, PSTR("%u"), uint_value));

Hier wurde ein unsigned int zurückgegeben.

Bekanntmachen

Nun musst du deine Funktion noch dem Rest der Firmware bekannt machen. Füge daher ganz unten in der Datei folgendes ein:

/*
-- Ethersex META --
block(Cooles Modul)
ecmd_feature(FUNCTIONSNAME, "NEW ECMD COMMAND",, DESCRIPTION)
ecmd_feature(FUNCTIONSNAME2, "NEW ECMD COMMAND2",VAL1 VAL2 VAL3, DESCRIPTION)
*/

Makefile erweitern

Läuft analog zu normalen anderen Quellcode Dateien.

ECMD Geschwindigkeit

Wenn du dein ethersex mit ECMD in einer hochen Geschwindigkeit angesprechen möchtest, ist für dich die Rate wichtig, in der das ethersex in der Lage ist, ECMD Anfragen zu beantworten. Hierzu gibt es eine kleine Untersuchung, einen Benchmark:

Beantwortete Anfragen pro Sekunde, Weg der Anfrage, gesandtes ECMD 480 pro Sekunde, Netzwerk, ECMD adc get 17 pro Sekunde, T-DSL 2000, ECMD adc get 32 pro Sekunde, RS232 115200 baud, ECMD adc get 627 pro Sekunde, Netzwerk, ECMD whm