{"id":16021983,"url":"https://github.com/tfry-git/embajax","last_synced_at":"2025-08-05T22:37:15.521Z","repository":{"id":51241248,"uuid":"123405274","full_name":"tfry-git/EmbAJAX","owner":"tfry-git","description":"Simplistic framework for creating and handling displays and controls on a web page served by an Arduino (or other small device).","archived":false,"fork":false,"pushed_at":"2024-09-09T13:56:37.000Z","size":5467,"stargazers_count":43,"open_issues_count":7,"forks_count":14,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-05-07T04:09:05.195Z","etag":null,"topics":["ajax","arduino","c-plus-plus","controls","esp8266","html","internet-of-things","iot","javascript","webserver"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tfry-git.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-03-01T08:28:18.000Z","updated_at":"2025-03-02T13:39:55.000Z","dependencies_parsed_at":"2024-09-09T16:28:09.582Z","dependency_job_id":"1e261f02-d1d4-4faf-9187-361ca3209d75","html_url":"https://github.com/tfry-git/EmbAJAX","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/tfry-git/EmbAJAX","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tfry-git%2FEmbAJAX","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tfry-git%2FEmbAJAX/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tfry-git%2FEmbAJAX/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tfry-git%2FEmbAJAX/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tfry-git","download_url":"https://codeload.github.com/tfry-git/EmbAJAX/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tfry-git%2FEmbAJAX/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268986679,"owners_count":24340637,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-05T02:00:12.334Z","response_time":2576,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["ajax","arduino","c-plus-plus","controls","esp8266","html","internet-of-things","iot","javascript","webserver"],"created_at":"2024-10-08T18:06:38.023Z","updated_at":"2025-08-05T22:37:15.436Z","avatar_url":"https://github.com/tfry-git.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# EmbAJAX\n\nSimplistic framework for creating and handling displays and controls on a web page served by an embeddable device (Arduino or other\nmicrocontroller with Arduino support).\n\n## Documentation\n\n- Overview, basic usage example, troubleshooting basic problems: **Continue reading on this page**\n- More usage examples: The regular [examples folder](/examples)\n- All functions / classes: [full API reference](https://tfry-git.github.io/EmbAJAX/api/annotated.html)\n- Tweaking RAM, flash, and network usage, understanding internal workings: [Technical details](/docs/Technical.md)\n\n## Overview\n\nIn the Arduino world, it has become astonishingly easy to create a web server on a microprocessor. But at the same time there is a\nsurprising lack of libraries to facilitate common tasks such as displaying some meter readings in textual or numeric displays, and\nkeeping those up-to-date on the client, or providing basic HTML controls such as sliders, radio buttons, and pushbuttons to control\nthe operation of the microprocessor.\n\nWhile many, many projects are doing exactly this, each seems to have to implement the wheel anew. The goal of the present project is\nto provide a basic but extensible framework to take care of these common tasks, so that you can focus on the actual functionality.\n\nI.e. the core features are:\n- Ability to \"print\" common controls to an HTML page \n- Automatic addition of AJAX code to relay control information from the client to the server and back\n- Automatic handling of the AJAX requests on the server side\n- Object-based representation of the controls on the web page. The programmer can simply interact with local objects, while the\n  framework takes care of keeping information in sync with the client.\n- Allows multiple clients to interact with the same page, concurrently.\n  - You can even pass information between two clients this way: Try loading the example, below, in two separate browsers!\n- Supports arbitrary number of pages, and elements can be shared across pages.\n- Simple but effective error handling for unreliable connections and server reboots\n\nThis framework _could_ be used independently of the Arduino environment, but Arduino is the main target, thus the C++ implementation,\nand a focus on keeping things lean in memory.\n\n## Status\n\nThe library is still pretty new, but quite functional, and stabilizing. This means you can start using the library right now.\nHowever, please note, that there is _no_ guarantee that upcoming versions of this library remain 100% compatible with the current\nversion. I'll try not to break things _except_ when there is a good reason to. Be aware that this \"promise\" applies to \"released\"\nversions, only, however. Inside the git master branch, breaking changes may happen more frequently.\n\nFor details on what has been changed, refer to the [ChangeLog](/docs/ChangeLog.md).\n\n### Supported elements / features\n\nThese controls / elements are supported as of now:\n\n- Checkboxes\n- Radio buttons (mutually exclusive buttons)\n- Push buttons\n- Sliders\n- Text display\n- Text input\n- Drop down option select\n- RGB Color picker\n- Directional input (\"joystick\")\n- Static HTML blocks\n- Connection status indicator\n\nThe following additional features may be of interest (supported as of now):\n\n- Allows to insert your own custom CSS for styling (no styling in the lib).\n  - See the \"Styling\"-example for techniques that can be used to define styling\n- Elements can be hidden, inputs can be disabled from the server (EmbAJAXBase::setVisible(), setEnabled()).\n\n### Hardware support\n\nCurrently EmbAJAX will work, without additional configuration using WiFi on ESP8266, ESP32, and Raspberry Pi Pico.\n\nFor the general approach on using EmbAJAX with different hardware, see the Blink_Ethernet example. This relies on the EthernetWebServer library,\nwhich supports a large number of different boards, including ATMEGA 2560, Teensy, etc. In a similar fashion, it should be possible to utilize the\nWiFiWebServer library for boards that do not include native WiFi (this latter claim has not currently been tested).\n\nShould your hardware need more custom tweaking, or you wish to use a different webserver library, drivers are really easy to add.\nAll that is needed is a very basic abstraction across some web server calls.\n\n#### ESP32 quirks and workaround\n\nUnfortunately, ESP32-support is currently plagued by a bug in the ESP32's networking code, that causes incoming connections\nto fail under some circumstances (https://github.com/espressif/arduino-esp32/issues/1921). If you are using ESP32, and EmbAJAX\nfeels sluggish, displays do not update, or the status indicator sometimes turns red, despite good network strength, you are probably\nbeing hit by this bug.\n\nYou can work around this by using the ESPAsyncWebServer library (https://github.com/me-no-dev/ESPAsyncWebServer). To do so,\n(after installing the lib), you will need to add:\n\n```cpp\n#include \u003cAsyncTCP.h\u003e\n#include \u003cEmbAJAXOutputDriverESPAsync.h\u003e\n```\n\n**above** ```#include \u003cEmbAJAX.h\u003e``` in your EmbAJAX sketches. No further adjustments are needed in the examples, provided, here.\n\n## Example sketch\n\nNot really useful, but you know what to really do with a slider, and a display, right?\nSome further examples can be found in the examples folder.\n\n```cpp\n#include \u003cEmbAJAX.h\u003e\n\n// Set up web server, and register it with EmbAJAX. Note: EmbAJAXOutputDriverWebServerClass is a\n// convenience #define to allow using the same example code across platforms\nEmbAJAXOutputDriverWebServerClass server(80);\nEmbAJAXOutputDriver driver(\u0026server);\n\n// Define the main elements of interest as variables, so we can access them later in our sketch.\nEmbAJAXSlider slider(\"slider\", 0, 500, 400);      // slider, from 0 to 500, initial value 400\nEmbAJAXMutableSpan display(\"display\");            // a plain text display\n\n// Define a page (named \"page\") with our elements of interest, above, interspersed by some uninteresting\n// static HTML. Note: MAKE_EmbAJAXPage is just a convenience macro around the EmbAJAXPage\u003c\u003e-class.\nMAKE_EmbAJAXPage(page, \"EmbAJAXTest\", \"\",\n  new EmbAJAXStatic(\"\u003ch1\u003eThis is a test\u003c/h1\u003e\u003cp\u003eThe value you set in the following slider: \"),\n  \u0026slider,\n  new EmbAJAXStatic(\" is sent to the server...\u003c/p\u003e\u003cp\u003e... which displays it here: \u003cb\u003e\"),\n  \u0026display,\n  new EmbAJAXStatic(\"\u003c/b\u003e\u003c/p\u003e\")\n)\n\nvoid setup() {\n  // Example WIFI setup as an access point. Change this to whatever suits you, best.\n  WiFi.mode(WIFI_AP);\n  WiFi.softAPConfig (IPAddress (192,168,4,1), IPAddress (0,0,0,0), IPAddress (255,255,255,0));\n  WiFi.softAP(\"EmbAJAXTest\", \"12345678\");\n\n  // Tell the server to serve our EmbAJAX test page on root\n  // installPage() abstracts over the (trivial but not uniform) WebServer-specific instructions to do so\n  driver.installPage(\u0026page, \"/\", updateUI);\n  server.begin();\n\n  updateUI();  // initialize display\n}\n\nchar buf[16];\nvoid updateUI() {\n  // And the following line is all that is needed to read the slider value, convert to a string, and send it\n  // back to the client for display:\n  display.setValue(itoa(slider.intValue(), buf, 10));\n\n  // NOTE: Instead of in this separate function, you could also place the above line in loop(). However, having\n  // it here allows the library to send back the updated display, immediately, resulting in a snappier UI on\n  // the client.\n}\n\nvoid loop() {\n    // handle network. loopHook() simply calls server.handleClient(), in most but not all server implementations.\n    driver.loopHook();\n}\n\n```\n\n## Installation\n\nEmbAJAX is available from the (Arduino Library Manager)[https://docs.arduino.cc/software/ide-v2/tutorials/ide-v2-installing-a-library].\n\nIf, instead, you want to use the bleeding edge version of EmbAJAX, the suggested routine is to _first_ install from the Library Manager, anyway, then\n_replace_ the contents of the installation folder with either a ```git clone``` of this repository, or _the contents_ of an unpackaged ZIP:\nhttps://github.com/tfry-git/EmbAJAX/archive/master.zip . The important thing is that the library installation folder itself _must_ be named \"EmbAJAX\",\nwhile - quite unfortunately - in the ZIP file, the folder is called \"EmbAJAX-master\".\n\n## A word on security\n\nAt present, EmbAJAX does not incorporate any security mechanisms. Anybody who can connect to the server will be able to view and\nset any control. So any security will have to be implemented on the network level.\n\nOne easy way to do so, that will suit many simple use cases - and is used in the examples - is to simply set up your device as a WiFi access point,\nwith encryption and password protection. With this, any client in range can connect, _if_ they have the credentials for the access point.\n\nIf you need remote connections, currently your best bet will be to use an nginx proxy server (see e.g. https://jjssoftware.github.io/secure-your-esp8266/).\n\nFuture versions of EmbAJAX will provide a basic authentication and permission system, but to provide any meaningful level of security, this will\nmean communication with your device will have to be encrypted. One exciting news in this regard is that an HTTPS server implementation is about to be\nadded to the ESP8266 arduino core. So check back soon (or submit your pull request)!\n\n## Some TODOs\n\n- More controls:\n  - One nice to have idea: A sort of \"touch-screen\", reporting clicks, and releases with exact position, continuous reporting of\n    mouse position (optional: always, never, while button pressed).\n    - Bonus points: With position marker (\"cursor\"), with ability to load arbitrary background image.\n  - Toggle buttons (trivial to implement on top of pushbuttons)\n- More drivers\n- More examples\n- Basic authentication / permission features\n  - Will need to rely on encrypted communication. I.e. HTTPS server implementation.\n\n## The beggar's line\n\nSo far everbody else has been rolling their own piece of AJAX for their own little project, and that's what I could have done, too, in a tiny\nfraction of the time spent on this framework, including its docs. But I chose to write all this, instead. Because I believe in re-usable solutions\nand shared efforts. If you do too, and this framework is useful to you, consider dropping a micro-donation via PayPal to thomas.friedrichsmeier@gmx.de .\nThanks!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftfry-git%2Fembajax","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftfry-git%2Fembajax","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftfry-git%2Fembajax/lists"}