{"id":20690201,"url":"https://github.com/per1234/etherevent","last_synced_at":"2026-04-24T21:32:00.529Z","repository":{"id":20876503,"uuid":"24163606","full_name":"per1234/EtherEvent","owner":"per1234","description":"Easy to use password authenticated Ethernet communication between Arduinos and EventGhost Network Event Sender/Receiver or TCPEvents plugins.","archived":false,"fork":false,"pushed_at":"2020-08-25T19:48:57.000Z","size":356,"stargazers_count":0,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-14T20:45:56.053Z","etag":null,"topics":["arduino","arduino-library","eventghost"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/per1234.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-09-17T21:46:56.000Z","updated_at":"2017-01-13T11:36:34.000Z","dependencies_parsed_at":"2022-08-03T12:00:33.751Z","dependency_job_id":null,"html_url":"https://github.com/per1234/EtherEvent","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/per1234/EtherEvent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/per1234%2FEtherEvent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/per1234%2FEtherEvent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/per1234%2FEtherEvent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/per1234%2FEtherEvent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/per1234","download_url":"https://codeload.github.com/per1234/EtherEvent/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/per1234%2FEtherEvent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32241611,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T13:21:15.438Z","status":"ssl_error","status_checked_at":"2026-04-24T13:21:15.005Z","response_time":64,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arduino","arduino-library","eventghost"],"created_at":"2024-11-16T23:12:13.417Z","updated_at":"2026-04-24T21:32:00.515Z","avatar_url":"https://github.com/per1234.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"EtherEvent\n==========\n\nEasy to use [Arduino](http://arduino.cc) library for password authenticated network communication via Ethernet between Arduinos and [EventGhost](http://eventghost.com), or any other program compatible with the EventGhost Network Event Sender and Receiver plugins. Compatible with Arduino Ethernet, Ethernet Shield, and other devices using the W5100/W5200/W5500 Ethernet controller.\n\n\n#### Compatible Software\n- Free\n  - Tested to work with this library:\n    - EventGhost: http://eventghost.com - Free open source automation tool for Windows. The Network Event Sender and Receiver plugins are compatible with EtherEvent.\n    - TCPEvents EventGhost plugin: https://github.com/per1234/TCPEvents - Improved network event sender/receiver allows sending events to multiple IP addresses.\n    - EgiGeoZone Geofence: https://play.google.com/store/apps/details?id=de.egi.geofence.geozone with the Arduino EtherEvent plugin: https://play.google.com/store/apps/details?id=de.egi.geofence.geozone.plugin.arduinoetherevent\n    - EventGhost automation with LabVIEW: http://decibel.ni.com/content/docs/DOC-13135 - LabVIEW network event sender and receiver VI. The receiver requires a large timeout value.\n  - Untested:\n    - eventghost-android: http://github.com/timhoeck/eventghost-android - Android network event app\n    - EGRemote Lite: http://play.google.com/store/apps/details?id=eu.rml.lab.egremote_lite - Android network event app\n    - RemoteGhost: http://forum.xda-developers.com/showthread.php?t=2076716 - Windows Phone network event app\n    - ProntoScript Library: http://remotecentral.com/cgi-bin/mboard/prontopro/thread.cgi?3646 - Philips Pronto Home Control Panel communication\n    - Android/Eventghost Communication Suite: http://ip-symcon.de/forum/threads/19614-Android-Eventghost-Communication-Suite - IP-Symcon(pay software) automation system communication\n- Pay\n  - Untested:\n    - terRemote - Android network event app\n    - EGRemote - Android network event app\n    - RemoteGhostPro - Windows Phone network event app\n\n\n#### Related Programs\n- EtherEventQueue outgoing event queue library: http://github.com/per1234/EtherEventQueue\n- Modified Ethernet library - allows the use of `EtherEvent.senderIP()`: http://github.com/per1234/EthernetMod - make sure to choose the correct branch for your Arduino IDE version. The [W5x00 branch](https://github.com/per1234/EthernetMod/tree/W5x00) supports W5100, W5200 and W5500 Ethernet controllers.\n- Wiznet Ethernet library provides another option for use with W5200 or W5500 Ethernet controllers: https://github.com/embeddist/WIZ_Ethernet_Library-IDE1.5.x\n\n\n\u003ca id=\"installation\"\u003e\u003c/a\u003e\n#### Installation\n- 32kB is the minimum recommended flash memory capacity for use of this library.\n- Download the most recent version of EtherEvent here: https://github.com/per1234/EtherEvent/archive/master.zip\n- Using Arduino IDE 1.0.x:\n  - **Sketch \u003e Import Library... \u003e Add Library... \u003e** select the downloaded file **\u003e Open**\n- Using Arduino IDE 1.5+:\n  - **Sketch \u003e Include Library \u003e Add ZIP Library... \u003e** select the downloaded file **\u003e Open**\n- Repeat this process with any other required libraries.\n  - ArduinoMD5 http://github.com/tzikis/ArduinoMD5 - Not required if you disable event authentication.\n  - If you want to use `EtherEvent.senderIP()` then you must install the modified Ethernet library: http://github.com/per1234/EthernetMod\n- Running the example sketch:\n  - File \u003e Examples \u003e EtherEvent \u003e BasicUsage\n  - Enable DHCP or set the device IP address, this can be any available IP address on your network.\n  - Set the device MAC address. This can be any address not already used on your network\n  - Set the EtherEvent password. The password must be the same on all connected devices.\n  - Upload to device\n  - Repeat with other connected devices.\n  - Details of the test communications will be printed to the serial monitor.\n\n\n#### About Events and Payloads\nEvents are used to trigger an action. The payload is information that accompanies the event. An example is an event code that triggers the display of the payload. Some events don't require a payload and in this case the payload may be left blank.\n\n\n\u003ca id=\"usage\"\u003e\u003c/a\u003e\n#### Usage\nSee the example sketches at **File \u003e Examples \u003e EtherEvent** and the EventGhost tree files in the **examples/EventGhost-example-trees** folder for demonstration of library usage.\n\n##### `#include \u003cEtherEvent.h\u003e`\nAllow access to the functions of the EtherEvent library.\n\n##### `#define ETHEREVENT_NO_AUTHENTICATION`\nAdd this line above the `#include \u003cEtherEvent.h\u003e` line in your sketch to disable password authentication. Requires [my version of the TCPEvents plugin](https://github.com/per1234/TCPEvents) with the password fields left blank in the configurations for communication with EventGhost. With authentication disabled the ArduinoMD5 library is not required, no need to set the password, memory usage is decreased significantly, and event transmission speed is increased. See the NoAuthentication example for a demonstration.\n\n##### `#define ETHEREVENT_FAST_SEND`\nIncrease sending speed at the expense of increased memory use. Add this line above the `#include \u003cEtherEvent.h\u003e` line in your sketch. This significantly increases the speed of sending __FlashStringHelper(`F()` macro) events/payloads but also increases the sketch size and SRAM usage during the send process. ETHEREVENT_FAST_SEND also increases the speed of sending some other event/payload types.\n\n##### `EtherEvent.begin([eventLengthMax, payloadLengthMax])`\nInitialize EtherEvent.\n- Parameter(optional): **eventLengthMax** - The maximum length of event that can be received. Longer events will be truncated to this length. EtherEvent reserves SRAM to buffer the received event so this value affects the amount of memory used. The default value is 15.\n  - Type: byte\n- Parameter(optional): **payloadLengthMax** - The maximum length of payload that can be received. Longer payloads will be truncated to this length. EtherEvent reserves SRAM to buffer the received payload so this value affects the amount of memory used. The default value is 100.\n  - Type: unsigned int\n- Returns: `true` = success, `false` = memory allocation failed\n  - Type: boolean\n\n##### `EtherEvent.setPassword(password)`\nSet the password. This is not required if authentication is disabled.\n- Parameter: **password** - Password used to authenticate event transmission.\n  - Type: char array or __FlashStringHelper(`F()` macro)\n- Returns: `true` = success, `false` = memory allocation failed\n  - Type: boolean\n\n##### `EtherEvent.availableEvent(ethernetServer[, cookie[, password]])`\nReceives new event if an event is not already buffered.\n- Parameter: **ethernetServer** - The EthernetServer object created in the Ethernet setup of the user's sketch.\n  - Type: EthernetServer\n- Parameter(optional): **cookie** - Cookie value to use in the authentication process. This can be used to provide a truly random cookie for enhanced security. If this parameter is not specified then a pseudorandom cookie will be generated using `random()`.\n  - Type: long\n- Parameter(optional): **password** - Password to use for the current event send. If the password parameter is used then the cookie parameter must be specified(If you want EtherEvent to generate your cookie then use `false` for the cookie parameter).\n  - Type: char array, __FlashStringHelper(`F()` macro)\n- Returns: Buffer size required to receive the event. This is the length of the received event and the null terminator minus the amount of the event already read.\n  - Type: byte\n\n##### `EtherEvent.availableEvent()`\n- Returns: Length of the received event and the null terminator minus the amount of the event already read.\n  - Type: byte\n  \n##### `EtherEvent.availablePayload()`\n`EtherEvent.availableEvent()` must be called first.\n- Returns: Buffer size required to receive the payload. This is the length of the received payload and the null terminator minus the amount of the payload already read.\n  - Type: unsigned int\n\n##### `EtherEvent.readEvent(eventBuffer)`\nPuts the event in the passed array. `EtherEvent.availableEvent()` must be called first, size a char array according to the result and pass it to `EtherEvent.readEvent()`. After that it will contain the event.\n- Parameter: **eventBuffer** - Buffer to hold the received event.\n  - Type: char array\n- Returns: none\n\n##### `EtherEvent.readEvent()`\n- Returns: The next character of the event.\n  - Type: char\n  \n##### `EtherEvent.readPayload(payloadBuffer)`\nPuts the payload string in the passed array. `EtherEvent.availableEvent()` must be called first, size a char array according to the result and pass it to `EtherEvent.readPayload()`. After that it will contain the payload.\n- Parameter: **payloadBuffer** - Buffer to hold the received payload.\n  - Type: char array\n- Returns: none\n\n##### `EtherEvent.readPayload()`\n- Returns: The next character of the payload.\n  - Type: char\n  \n##### `EtherEvent.senderIP()`\nReturns the IP address of the sender of the most recent event. Must have the [modified Ethernet library](http://github.com/per1234/EthernetMod) installed for this function to be available.\n- Returns: IP address of the sender.\n  - Type: IPAddress\n\n##### `EtherEvent.flushReceiver()`\nClear any buffered event and payload data so a new event can be received.\n- Returns: none\n\n##### `EtherEvent.send(ethernetClient, target, port, event[, payload[, password]])`\nSend an event and payload.\n- Parameter: **ethernetClient** - The EthernetClient object created in the Ethernet setup of the user's sketch.\n  - Type: EthernetClient\n- Parameter: **target** - IP address to send the event to.\n  - Type: IPAddress or byte(4 byte array)\n- Parameter: **port** - Port to send the event to.\n  - Type: unsigned int\n- Parameter: **event**\n  - Type: char array, int8_t, byte, int, unsigned int, long, unsigned long, __FlashStringHelper(`F()` macro), String, IPAddress, float, double, Printable\n- Parameter(optional): **payload** - Payload to send with the event.\n  - Type: char array, int8_t, byte, int, unsigned int, long, unsigned long, __FlashStringHelper(`F()` macro), String, IPAddress, float, double, Printable\n- Parameter(optional): **password** - Password to use for the current event send. If the password parameter is used then the payload parameter must be specified(If there is no payload use `\"\"`).\n  - Type: char array, __FlashStringHelper(`F()` macro)\n- Returns: `true` = success, `false` = failure\n  - Type: boolean\n\n##### `EtherEvent.setSendDoubleDecimalPlaces(decimalPlaces)`\nSet the number of decimal places when sending double or float type events and payloads. This function is only available if `ETHEREVENT_FAST_SEND` is defined. In normal mode only two decimal places are supported.\n- Parameter: **decimalPlaces** - The initial value is 3.\n  - Type: byte\n- Returns: none\n\n##### `EtherEvent.getTimeout()`\nReturns the current timeout duration setting.\n- Returns: The current timeout duration setting.\n  - Type: unsigned int\n\n##### `EtherEvent.setTimeout(timeout)`\nSet the timeout duration(Stream functions).\n- Parameter: **timeout** - The maximum time to wait for Ethernet communication in milliseconds.\n  - Type: unsigned int\n- Returns: none\n\n\n\u003ca id=\"troubleshooting\"\u003e\u003c/a\u003e\n#### Troubleshooting\n- Network configuration:\n  - The MAC address you choose for the device must be unique on your network.\n  - If using a static IP address it must be unique on your network.\n  -  If using EventGhost, the firewall on the computer must allow it to communicate via the network.\n- Timeouts: When using the **BasicUsage.ino** example sketch you may notice sending or receiving an event sometimes will hang for a long time before failing. This is caused by the conservative default timeout values. **AdvancedUsage.ino** demonstrates setting the EtherEvent timeout via `EtherEvent.setTimeout()` and the W5x00 Ethernet controller timeout and retry count via `W5100.setRetransmissionTime()` and `W5100.setRetransmissionCount()`. `EtherEvent.setTimeout()` controls the amount of time that EtherEvent will wait for the authentication process communications. `W5100.setRetransmissionTime()` controls the amount of time that the W5x00 will wait after a connection attempt before retrying. `W5100.setRetransmissionCount()` controls the number of attempts the W5x00 will make before failing the connection attempt. By reducing the timeout values you can shorten the amount of time that the system will hang during a failed event transmission. If the timeout values are too small then you will see frequent transmission failures. By experimenting with different values you can find appropriate timeouts for your system. Be aware that the timeout requirements for Arduino to EventGhost event transmission may be different than Arduino to Arduino transmission.\n- Debug output: By turning debug output on you can get details of the authentication process in the serial monitor. Set `#define ETHEREVENT_DEBUG true` in EtherEvent.h, this will slow down communication and increase memory usage so only enable when needed. The default speed of the debug serial output is 9600 but this can be changed in the line `const unsigned long debugSerialBaud = 9600;` in **EtherEvent.h**\n- If EventGhost recieves an event that contain '.' the standard event prefix will disappear from that event. This is a limitation of EventGhost, not EtherEvent.\n\n\n\u003ca id=\"security\"\u003e\u003c/a\u003e\n#### Security Considerations\n- If security is not necessary for your application you can disable authentication(see the NoAuthentication example).\n- EtherEvent only encrypts the authentication password. The event is sent in plaintext. This prevents the receipt of unauthorized events but does not protect the information contained in the event from being seen.\n- Use of EventGhost Network Event Receiver plugin in EventGhost versions previous to 4.0.1.r1710 is not recommended due to a bug that causes it to send the same cookie for every event. My [modified TCPEvents EventGhost plugin](https://github.com/per1234/TCPEvents) has this security vulnerability patched.\n- Cookie Randomization: an important factor in the authentication security is the randomness of the cookie supplied by the event receiver. There is a trade-off between security and memory usage/speed so the ideal level of cookie randomization depends on your application.\n  - Default operation: If a cookie is not supplied then EtherEvent uses the value of `micros()` for a seed and produces the cookie using `random()`.\n  - User supplied cookie: You can generate your own random cookie and pass the value to `EtherEvent.availableEvent()`.\n    - Entropy library: A truly random number can be generated by the Entropy library and used for every cookie. This will cause greater flash memory usage and slower authentication. See the example sketch **Entropy.ino** for demonstration of use of the Entropy library with EtherEvent.\n\n\n\u003ca id=\"process\"\u003e\u003c/a\u003e\n#### Authentication Process\nEventGhost uses MD5 encrypted APOP style authentication to avoid sending passwords in plaintext.\n- sender: Connect to receiver. Send `quintessence\\n\\r`.\n- receiver: Send cookie.\n- sender: The password is appended to the cookie and the MD5 digest is calculated and sent back to the receiver.\n- receiver: If the received MD5 digest is correct then it sends `accept`.\n- sender: Send `payload {payload string}\\n{event}\\nclose\\n` to the receiver.\n- receiver: Close the connection to the sender.\n\n\n#### Contributing\nPull requests or issue reports are welcome! Please see the [contribution rules](https://github.com/per1234/EtherEvent/blob/master/CONTRIBUTING.md) for instructions.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fper1234%2Fetherevent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fper1234%2Fetherevent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fper1234%2Fetherevent/lists"}