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	Netzwerk	adc get
17	T-DSL 2000	adc get
32	RS232 115200 baud	adc get
627	Netzwerk	whm

Diese Werte wurden mithilfe des Python-Projekts avrnetio von pklaus ermittelt, das auf http://github.com/pklaus/avrnetio zu finden ist. Für die serielle Kommunikation wird pySerial verwendet, für Netzwerk python sockets. Die verwendete ethersex Version ist der Commit e9c89... mit einer Laufzeit von mittlerweile 817 Stunden (34 days). Die getestete Hardware ist ein Pollin AVR-NET-IO mit ATMega32.