{"id":21743643,"url":"https://github.com/kmanoz/kmansonoff","last_synced_at":"2025-07-27T09:12:25.782Z","repository":{"id":139284626,"uuid":"109199185","full_name":"KmanOz/KmanSonoff","owner":"KmanOz","description":"Firmware for ESP8266 based itead Sonoff switches for use with HomeAssistant / mqtt","archived":false,"fork":false,"pushed_at":"2018-03-01T15:02:28.000Z","size":2665,"stargazers_count":283,"open_issues_count":21,"forks_count":39,"subscribers_count":39,"default_branch":"master","last_synced_at":"2025-04-08T04:18:10.154Z","etag":null,"topics":["arduino-ide","firmware","home-assistant","home-automation","iot-device","mqtt","mqtt-client","ota","relay","sonoff","sonoff-switches","switch"],"latest_commit_sha":null,"homepage":null,"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/KmanOz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2017-11-02T00:35:23.000Z","updated_at":"2024-12-26T01:47:30.000Z","dependencies_parsed_at":null,"dependency_job_id":"508bd8fc-be6a-40af-8f48-2f6dd19295f6","html_url":"https://github.com/KmanOz/KmanSonoff","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/KmanOz/KmanSonoff","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KmanOz%2FKmanSonoff","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KmanOz%2FKmanSonoff/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KmanOz%2FKmanSonoff/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KmanOz%2FKmanSonoff/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KmanOz","download_url":"https://codeload.github.com/KmanOz/KmanSonoff/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KmanOz%2FKmanSonoff/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259519177,"owners_count":22870324,"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","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-ide","firmware","home-assistant","home-automation","iot-device","mqtt","mqtt-client","ota","relay","sonoff","sonoff-switches","switch"],"created_at":"2024-11-26T07:08:39.109Z","updated_at":"2025-06-12T18:32:31.184Z","avatar_url":"https://github.com/KmanOz.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# KmanSonoff - Alternative firmware for Sonoff Switches\r\n\r\n![](images/sonoff.png \"Sonoff Range\")\r\n\r\nKmanSonoff is the updated version of [KmanOz/Sonoff-HomeAssistant](https://github.com/KmanOz/Sonoff-HomeAssistant) which is alternative firmware for the brilliant \u0026 cheap range of ESP-8266 based WiFi controlled power switches. This updated firmware simplifies setup of the switch even more so than the original, yet keeps the firmware and memory footprint basic and lightweight just like it's predecessor. Initial setup is now done in one file \"config_sc.h\" for the single channel firmware or \"config_mc.h\" for the multichannel firmware located in the same directory as the sketch. Both versions are OTA upgradable and all naming (mqtt client name \u0026 mDNS for OTA) is automatic based on the MAC address of the ESP Wifi radio.\r\n\r\nI realize there are many other mqtt based firmware(s) that have been written for the Sonoff switches, but I found most of them overly complex for my liking. This firmware is basic in operation but ***extremely stable*** and just gets the job done.\r\n\r\n#### Currently Supported Devices (More to come)\r\n\r\n- [Sonoff Basic](https://www.itead.cc/smart-home/sonoff-wifi-wireless-switch.html?acc=70efdf2ec9b086079795c442636b55fb)\r\n- [Sonoff RF](https://www.itead.cc/smart-home/sonoff-rf.html?acc=70efdf2ec9b086079795c442636b55fb)\r\n- [Sonoff Slampher](https://www.itead.cc/slampher.html?acc=70efdf2ec9b086079795c442636b55fb)\r\n- [Sonoff TH10/TH16](https://www.itead.cc/sonoff-th.html?acc=70efdf2ec9b086079795c442636b55fb)\r\n- [Sonoff Touch](https://www.itead.cc/smart-home/sonoff-touch.html?acc=70efdf2ec9b086079795c442636b55fb)\r\n- [Sonoff S20](https://www.itead.cc/smart-home/smart-socket.html?acc=70efdf2ec9b086079795c442636b55fb)\r\n- [Sonoff SV](https://www.itead.cc/smart-home/sonoff-sv.html?acc=70efdf2ec9b086079795c442636b55fb)\r\n- [Sonoff 4CH](https://www.itead.cc/smart-home/sonoff-4ch.html?acc=70efdf2ec9b086079795c442636b55fb)\r\n- [Sonoff 4CH PRO](https://www.itead.cc/sonoff-4ch-pro.html?acc=70efdf2ec9b086079795c442636b55fb)\r\n- [Sonoff T1 (Up to 3 Ch)](https://www.itead.cc/sonoff-t1.html?acc=70efdf2ec9b086079795c442636b55fb)\r\n\r\nYou'll need the Arduino IDE and has been tested on 1.8.5 but should be backwards \u0026 forwards compatible with other versions.\r\n\r\n## Configuration\r\n\r\n**1. Clone the Repository**\r\n\r\nClone the **KmanSonoff** repository to your local machine. Copy the required version for your switch to your Arduino directory.\r\n\r\n``` bash\r\n$ git clone https://github.com/KmanOz/KmanSonoff\r\n```\r\n**2. Clone the LMROY version of the mqtt library**\r\n\r\nI use the [lmroy](https://github.com/Imroy/pubsubclient) version of this excellent mqtt library, mainly because it supports QOS1 and keepalive settings right from within the sketch. No other modifications to library files are necessary.\r\n\r\nIt's currently setup to use only v3.1.1 of the mqtt standard and will only work on that version broker unless you modify the code so make sure your broker is setup to use v3.1.1 of the mqtt standard and not v3.1.\r\n\r\n**FOR ALL THE PEOPLE THAT SKIP THIS STEP, DON'T. YOU CANNOT USE OTHER MQTT LIBRARIES**\r\n\r\n``` bash\r\n$ git clone https://github.com/Imroy/pubsubclient\r\n```\r\n**3. Install DHT library (If Temperature reporting is enabled)**\r\n\r\nUning the Arduino IDE's Library Manager install the DHT library if you plan on enabling Temperature reporting.\r\n\r\n\r\n**3. Modify the details in the Arduino code (config.h) to your specific details and environment. (THIS IS IMPORTANT)**\r\n\r\nTo start off, change the \"WIFI_SSID, WIFI_PASS, MQTT_SERVER, MQTT_PORT, MQTT_USER, MQTT_PASS in the Arduino code provided to suit your environment. \r\n\r\n``` bash\r\n#define MQTT_SERVER     \"192.168.0.100\"                      // mqtt server\r\n#define MQTT_PORT       1883                                 // mqtt port\r\n#define MQTT_TOPIC      \"home/sonoff/living_room/1\"          // mqtt topic (Must be unique for each Sonoff)\r\n#define MQTT_USER       \"user\"                               // mqtt user\r\n#define MQTT_PASS       \"pass\"                               // mqtt password\r\n#define WIFI_SSID       \"homewifi\"                           // wifi ssid\r\n#define WIFI_PASS       \"homepass\"                           // wifi password\r\n```\r\n\r\nAdditionally other parameters can be changed in the file at your discretion like whether or not you wish to remember the last relay state, retain mqtt messages, update frequecy for WiFi retries etc. See \"config_sc.h or config_mc.h\" for all options.\r\n\r\n## Flashing the Firmware\r\n\r\nI will assume you have the necessary skills to complete this step. As mentioned earlier, you'll need the Arduino IDE and you'll need to move the files you just cloned to the right directories. There are plenty or tutorials that cover all the steps involved already published on the Internet and it's only a Google search away.\r\n\r\nAs for the switch modifications, it's simply a matter of opening up the switch, installing a 4 or 5 pin header (depending on switch type) and then holding down the main switch (or installing a jumper on some models) on the unit before you power it up with your FTDI adapter. You are then good to go to re-flash your new firmware. The photo below is for illustration only and different products will require the same basic connection but headers will be located in different positions etc. (If anyone is willing to help, feel free to do a PR and add detailed instructions for other switches. Sorry too busy).\r\n\r\n![alt FTDI Diagram](images/th10ftdi.JPG \"FTDI Diagram\")\r\n\r\n## HomeAssistant Integration\r\n\r\n**1. Modify configuration.yaml in HomeAssistant and add the following to it.**\r\n\r\n```bash\r\nswitch:\r\n  - platform: mqtt\r\n    name: \"Living Room\"\r\n    state_topic: \"home/sonoff/living_room/1/stat\"\r\n    command_topic: \"home/sonoff/living_room/1\"\r\n    qos: 0\r\n    payload_on: \"on\"\r\n    payload_off: \"off\"\r\n    retain: true\r\n```\r\nAssuming you make no changes to the topic in the code provided, you should be able to test the switch and be happy that you now have control using Home Assistant.\r\n\r\nIf you've the enabled temperature function, you can also setup sensors in HomeAssistant to display both Temperature \u0026 Humidity. Modify your configuration.yaml and add the following.\r\n\r\n```bash\r\nsensor:\r\n  - platform: mqtt\r\n    name: \"Living Room Temp\"\r\n    state_topic: \"home/sonoff/living_room/1/temp\"\r\n    qos: 1\r\n    unit_of_measurement: \"°C\"\r\n    value_template: \"{{ value_json.Temp }}\"\r\n  \r\n  - platform: mqtt\r\n    name: \"Living Room Humidity\"\r\n    state_topic: \"home/sonoff/living_room/1/temp\"\r\n    qos: 1\r\n    unit_of_measurement: \"%\"\r\n    value_template: \"{{ value_json.Humidity }}\"\r\n```\r\n\r\n## Commands and Operation\r\n\r\n**1. Commands**\r\n\r\nAs mentioned earlier, the commands are very basic. In fact the switch will respond to 4 basic mqtt commands and they are :-\r\n\r\n- **on** (Turns the relay and LED on)(For multi channel precede the *on* command by the channel no#. e.g 1on, 3on etc)\r\n- **off** (Turns the relay and LED off)(For multi channel precede the *off* command by the channel no#. e.g 2off, 3off etc)\r\n- **stat** (Returns the status of the switch via mqtt message)(For multi channel the channel no# will precede the status. e.g. 1on, 4off)\r\n- **reset** (Forces a restart of the switch) (4 long flashes of the status LED)\r\n\r\nIf you've enabled the temperature function, you have an additional option.\r\n\r\n- **temp** (Forces a temperature \u0026 humidity check otherwise it's reported every 1 minute) (1 short flash of the status LED)\r\n\r\n**2. Operation**\r\n\r\nWhen power is first applied the unit will immediately connect to your WiFi access point / router and your mqtt broker. When it connects the status LED will flash fast 4 times. That's it, your connected.\r\n\r\nIf you've enabled the temperature function, you will see a short single flash to indicate that the temperature \u0026 humidity has been published as well.\r\n\r\nPress the switch on top to turn on the relay. Press it again to turn it off and watch the status change in HomeAssistant. Toggle the switch in HomeAssistant and the relay \u0026 LED will toggle accordingly. If your switch allows for an external wallswitch to be connected and that feature is enable, you should now be able to toggle the status of the Sonoff with the external wallswitch as well. \r\n\r\nTo reset the switch manually, press and hold the switch for more than 4 seconds. (4CH press and hold Relay 1 switch) The switch will respond with 4 long flashes and reboot.\r\n\r\n## OTA Updates\r\n\r\nAssuming you have the correct environment setup for OTA (Python 2.7 installed) you can update the firmware via the Arduino IDE using OTA. The switch will publish it's name in the following format. (Sonoff_XXXXXX) X's will be replaced with the last 6 characters of the WiFi MAC address.\r\n\r\nWhen the unit enters OTA, the status LED will flash twice. Once entered and firmware is being updated the status LED will flash fast continuously as packets are received. If the upload was successful the status LED will remain ON and in a short amount of time will turn off. The switch will reset and the status LED will flash 4 times fast and reconnect.\r\n\r\nIf unsuccessful after it enters OTA upgrade mode, it will exit with 2 fast flashes of the Status LED and either resume normally, or reset depending on the error.\r\n\r\n## Versions\r\n\r\n**KmanSonoff_v1.00sc** - Single Channel firmware used for original iTead Sonoff Switch, Sonoff Touch, Sonof S20 Smart Socket, Sonoff SV etc\r\n\r\n**KmanSonoff_v1.00mc** - Multichannel firmware (Up to 4 Channels) used for Sonoff 4CH, 4CH Pro, Sonoff T1 (1, 2 \u0026 3 CH), etc\r\n\r\n## MIT License\r\n\r\nCopyright (c) 2017\r\n\r\nPermission is hereby granted, free of charge, to any person obtaining a copy\r\nof this software and associated documentation files (the \"Software\"), to deal\r\nin the Software without restriction, including without limitation the rights\r\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\r\ncopies of the Software, and to permit persons to whom the Software is\r\nfurnished to do so, subject to the following conditions:\r\n\r\nThe above copyright notice and this permission notice shall be included in all\r\ncopies or substantial portions of the Software.\r\n\r\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\r\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\r\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\r\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\r\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r\nSOFTWARE.\r\n\r\n## Conclusion\r\n\r\nThat's about it. Any feature suggestions are welcome and I would be happy to answer any further questions that you may have. Additionally of you would like to contribute to this library please feel free to do a PR.\r\n\r\n\r\nEnjoy!\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkmanoz%2Fkmansonoff","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkmanoz%2Fkmansonoff","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkmanoz%2Fkmansonoff/lists"}