{"id":16532067,"url":"https://github.com/ei-grad/water-pump-timer","last_synced_at":"2025-10-12T05:08:51.089Z","repository":{"id":66875124,"uuid":"144986973","full_name":"ei-grad/water-pump-timer","owner":"ei-grad","description":null,"archived":false,"fork":false,"pushed_at":"2024-02-01T09:38:33.000Z","size":29,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-09T23:58:18.102Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","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/ei-grad.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}},"created_at":"2018-08-16T12:49:07.000Z","updated_at":"2024-02-01T09:37:25.000Z","dependencies_parsed_at":"2024-02-01T10:37:14.394Z","dependency_job_id":"b85db13e-a3c0-4af2-b6ab-0d85e0c606b9","html_url":"https://github.com/ei-grad/water-pump-timer","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ei-grad%2Fwater-pump-timer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ei-grad%2Fwater-pump-timer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ei-grad%2Fwater-pump-timer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ei-grad%2Fwater-pump-timer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ei-grad","download_url":"https://codeload.github.com/ei-grad/water-pump-timer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241652944,"owners_count":19997575,"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":[],"created_at":"2024-10-11T18:11:35.213Z","updated_at":"2025-10-12T05:08:46.038Z","avatar_url":"https://github.com/ei-grad.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"Water pump timer for Sunsurfers Ecovillage\n==========================================\n\nThis repository contains the software to control the waterpump in [#Sunsurfers\nEcovillage](http://sunsurfers.ru/projects/eco-village-georgia/). It implements\nthe simple logic to turn on the pump for some time, then wait for some time and\nthen repeat. In future it would be triggered by water level monitor, but\ncurrently it just does the cycle for 10 times.\n\nThere is its [web UI screenshot](https://github.com/ei-grad/water-pump-timer/assets/78607/ec5181b8-cc88-40ef-9b0c-8caed300290a).\n\nThe board is ESP8266-01, running [micropython](http://micropython.org/). Its\nGPIO 0/2 pins are connected to two SRD-05VDC-SL-C relays.\n\nMicropython docs for ESP8266: https://docs.micropython.org/en/latest/esp8266/index.html\n\nFirmware and code\n-----------------\n\nThe firmware which is flashed to the board via esptool through the USB TTY is\nthe micropython firmware binary. It shouldn't be compiled manually, just take\nthe latest ESP8266 binary release from http://micropython.org/download#esp8266.\n\nDuring the boot this firmware runs the code from `boot.py` and `main.py` files\nlocated on the board's internal FAT filesystem, which only could be written and\naccessible from the Python REPL running on the board. The `main.py` also\nimports the code from additional python modules - `app.py`, `webform.py`, etc.\n\nTo execute the code the Python interpreter first compiles it to its bytecode\nrepresentation. This compilation normaly goes during the script execution or\nmodule import, just in the same environment where it is going to be executed\n(in the micropython interpreter running on the ESP8266, in our case).  But it\ncould be too demanding process in terms of memory resources, and micropython\nrunning on ESP8266 may not be able to compile some complex modules by itself.\nSo this modules have to be cross-compiled to `.mpy` files (analog of the\nCPython `.pyc` files). It is done with the\n[mpy-cross](https://github.com/micropython/micropython/tree/master/mpy-cross)\ntool before being deployed to ESP8266, see the `deploy.sh` script. The\n`main.py` and `boot.py` files shouldn't be compiled because they are always\nexecuted as a scripts, so it is reasonable to keep them short and simple.\n\nThe WebREPL interface could be used to put the `boot.py`, `main.py` and\npre-compiled modules to the ESP8266 internal FAT filesystem, see `deploy.sh`\nand the instructions in the next section how to use WebREPL to deploy the code.\nAlso, the REPL could be accessed via USB TTY interface, and it could be used\nfor this purpose too. There is a [adafruit\nampy](https://github.com/adafruit/ampy) tool for that purpose, but I had no\nluck to use it successfully yet.\n\nPrerequirements for build and deploy\n------------------------------------\n\n* `esptool`\n\nIt is needed to flush the micropython firmware.\n\n```bash\npip install esptool\n\n# copy it to be available without the .py suffix\ncp \"`which esptool.py`\" \"`which esptool.py | sed s/.py$//`\"\n```\n\nFIXME: Installation via `pip` may not work on MacOS default python because its\n`pip` version is too old.\n\nIn Debian and ArchLinux it is available in the official repositories.\n\nFor Debian:\n\n```\napt-get install esptool\n```\n\nFor ArchLinux\n\n```\npacman -S esptool\n```\n\n* `mpy-cross`\n\nThe `mpy-cross` tool from https://github.com/micropython/micropython is needed\nto precompile the modules into python bytecode.\n\nJust clone the micropython repository, enter the mpy-cross directory, then\n`make` and copy the built `mpy-cross` binary somewhere to the `$PATH`, for\nexample to `/usr/local/bin`.\n\n```bash\ngit clone https://github.com/micropython/micropython.git\ncd micropython/mpy-cross\nmake\nsudo cp ./mpy-cross /usr/local/bin/\n```\n\nFor more information see its\n[README.md](https://github.com/micropython/micropython/blob/master/mpy-cross/README.md).\n\n* `webrepl_cli`\n\nThe `webrepl_cli.py` tool from https://github.com/micropython/webrepl is needed\nto copy the code over WebREPL interface. It could be installed this way:\n\n```bash\ncurl https://raw.githubusercontent.com/micropython/webrepl/master/webrepl_cli.py \u003e /usr/local/bin/webrepl_cli\nchmod +x /usr/local/bin/webrepl_cli\nMODULES_DIR=/usr/local/lib/python`python -c \"import sys; print('{0.major}.{0.minor}'.format(sys.version_info))\"`/site-packages\npython -c \"import sys; assert '$MODULES_DIR' in sys.path\"\ncurl https://raw.githubusercontent.com/micropython/webrepl/master/websocket_helper.py \u003e \"$MODULES_DIR/websocket_helper.py\"\n```\n\nInitial board configuration\n---------------------------\n\n1. Connect ESP8266 via developer board to your PC in firmware mode (hold the\n   red button on the down side of the board while connecting).\n\n2. Erase the flash:\n\n```bash\nesptool -p /dev/ttyUSB0 -b 115200 erase_flash\n```\n\n3. Reattach the board holding red button again and load the micropython firmware to it:\n\n```bash\nesptool -p /dev/ttyUSB0 -b 115200 write_flash --flash_mode qio 0x0 ./esp8266-20180511-v1.9.4.bin\n```\n\n4. Reattach the developer board with ESP8266 in regular mode (not holding the red button).\n\n5. Connect to the TTY REPL:\n\n```bash\nscreen /dev/ttyUSB0 115200\n```\n\n6. Use the TTY REPL to connect the ESP8266 to WiFi:\n\nFirst save the wifi credentials to the storage, it would be used by `boot.py`\nscript to setup the WiFi connection during the boot:\n\n```python\nf = open('wifi-creds.txt', 'w')\nssid, password = 'ssid', 'password'  # \u003c-- replace them by actual values\nf.write('%s:%s' % (ssid, password))\nf.close()\n```\n\nThen up the WiFi connection:\n\n```python\nimport network\nwlan = network.WLAN(network.STA_IF)\nwlan.active(True)\nwlan.connect(ssid, password)\n```\n\nTo ensure that WiFi has been successfully connected and the device received the\nIP address from DHCP server check the `wlan.ifconfig()` output:\n\n```python\nprint('My IP address is', wlan.ifconfig()[0])\n```\n\n7. Enable the WebREPL and specify its password.\n\n```python\nimport webrepl_setup\n```\n\nIt would ask for required information interactively. Answer `y` to the reset\nconfirmation (it would do the \"soft reset\", keeping the WiFi connection\nactive). This reset is needed to run the WebREPL server.\n\n8. Build and upload code\n\nNow open the new terminal, clone this repository:\n\n```\ngit clone https://github.com/ei-grad/water-pump-timer.git\ncd water-pump-timer\n```\n\nPut the WebREPL password you have specified on previous step to the\n`WEBREPL_PASSWD` env variable and run `./deploy.sh`:\n\n```\nWEBREPL_PASSWD=password ./deploy.sh\n```\n\nDeploy process could hangup due to poor network error handling in webrepl\nserver-side code. If it happens - interrupt the `deploy.sh` with Ctrl-C, and\nthen return to the USB TTY console and restart the webrepl:\n\n```python\n\u003e\u003e\u003e import webrepl\n\u003e\u003e\u003e webrepl.start()\n```\n\nAnd then try to run the `./deploy.sh` again. The error could happen for a\ncouple of times in a row, just start the webrepl again and repeat.\n\n9. Reboot the board:\n\n```python\nfrom machine import reset\nreset()\n```\n\nor you could just reattach it to USB.\n\nYou now should be able to access the web interface on 80 port of the IP address\nyou could see in wlan.ifconfig() output.\n\nHow to connect to the WebREPL to execute commands interactively\n---------------------------------------------------------------\n\n1. Clone WebREPL: https://github.com/micropython/webrepl.git\n2. Open its webrepl.html in browser\n3. Enter the board address `ws://x.x.x.x:8266/` (where the `x.x.x.x` is the IP\n   address, which you can get from your WiFi router DHCP leases table, or on\n   the TTY while connecting the chip to developer board), and then push the\n   \"Connect\" button.\n4. Enter the WebREPL password\n\nTroubleshooting\n---------------\n\nThe FAT filesystem goes trash in some cases. Often the only way to recover the\ndevice is the full process described in the \"Initial board configuration\"\nsection, starting with `erase_flash` command, but in some cases when the REPL\nis still available (via WebREPL or USB TTY) formatting the FAT and running\n`deploy.sh` could be enough.\n\nFormat the FAT in REPL:\n\n```python\nimport uos\nimport flashbdev\nuos.VfsFat.mkfs(flashbdev.bdev)\n```\n\nRun `./deploy.sh` in water-pump-timer directory:\n\n```\nWEBREPL_PASSWD=password ./deploy.sh\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fei-grad%2Fwater-pump-timer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fei-grad%2Fwater-pump-timer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fei-grad%2Fwater-pump-timer/lists"}