Device Setup

The information in this document is based on the NodeMCU ESP8266 Development Board, but other devices will be similar. Please follow specific instructions for your particular device.

Assuming you have cloned the repository to your local machine, and chdir to the proxymow-mower folder, then there are a number of tasks to perform to get the mower device ready:

  1. Customise utils.py with Wi-Fi connection details
  2. Connect device to PC via USB
  3. Check driver has connected to identify port
  4. Erase flash memory
  5. Upload the MicroPython interpreter
  6. Deploy proxymow-mower files to device
  7. Enable WebREPL for remote management

Device Management Tools

There is a range of tools that can be used to complete the setup:

My favourite is rshell, which has a wide range of commands that can be assembled into a batch file. An example rshell script is provided scripts/device-setup.bat. This script performs tasks 4, 5, 6 and 7 in one go, providing the MicroPython interpreter bin file resides in the same folder as the script.

If you are unable to get rshell working on your platform, then the next best option is probably Thonny. Thonny is a full blown IDE, requiring each task to be performed interactively.

If Thonny is not an option, then esptool can be used to erase the flash, and upload the MicroPython interpreter. esptool is a plain python module, which should run on most platforms. From there you should be able to use a Terminal Emulator to connect to the device and enable WebREPL. WebREPL has a File Upload facility, enabling the application files to be uploaded.

Identifying the COM port

Device setup can be completed with a bare device and a USB cable to connect to the PC (Windows is assumed but other platforms will be similar). It is important to check the device has been detected by your PC. Before connecting, open Device Manager and expand the ports branch. Plug in the device cable and check the COM port that gets created (COM3 in the example below). This information will be needed for other setup tasks.

Device Manager Ports

Wi-Fi Connection Details

The mower robot has to connect to the network over Wi-Fi. The router ssid and password are stored in utils.py, with support for mowers that operate cross-lawn. For the setup to be finalised, these details will need to be changed to match your network. See the documentation on utils.py for further details.

MicroPython Interpreter

If you use Thonny to install this .bin file then it will download it for you and upload to the connected device. The default install options didn't work for my device, so I had to use the following:

Thonny Upload MicroPython

If installation is successful, hit Stop/Reset and you should see the following in the Thonny shell...

Thonny Shell

If you don't use Thonny to install the interpreter then you will have to visit https://micropython.org/download/ and manually select and download the appropriate file for your device. esptool can then be used to upload it:

esptool --chip esp8266 write_flash --flash_size detect 0 ESP8266_GENERIC-20240602-v1.23.0.bin

or to just erase the flash:

esptool --chip esp8266 erase_flash

Deploy proxymow-mower

If you run the rshell script it will upload the relevant .py files to the device, and all that is needed is a reset to start it up. If you use Thonny you need to use its explorer to locate the cloned repository and the following files:

  • utils.py
  • shared_utils.py
  • umotion_lib.py
  • schematic.py
  • artic.py
  • mower.py
  • main.py

Right click each of these files in the explorer and choose Upload to / You can see which files are on the device in the lower pane of the explorer. use the RST button on the device to restart after any file uploads.

Terminal Emulator

A Terminal Emulator like Putty can be used to access the device REPL prompt. Here is a typical configuration:

Putty Configuration

WebREPL

Once your device is installed in your robot mower it can be inconvenient to connect it to a PC with a USB lead. Sometimes this is necessary if the device has become corrupt, but for small changes involving single files it is much easier to use WebREPL in a browser to upload files and monitor activity. Follow the instructions for your device to enable it and gain access.

Note that all these tools do not play nicely together, so if you are switching between tools for different tasks, then you will probably need to close one before using the other.

Customise schematic.py

schematic.py is like a soft wiring diagram that contains the hardware mapping and service details. This module uses the MAC address to recognise the device and customise the software to reflect the nuances of the physical hardware attached. The advantage of this approach is that only one schematic source file needs to be managed, and it can be deployed to multiple robot mowers. This is a list of things that may need to customised for any particular mower:

  • Mower Name
  • Left and Right Speed Scale Factors
  • Analogue-to-Digital Converter (ADC) Enabled
  • I2C enabled

No two motors are identical, so the speed scale factors provide an opportunity to even out any discrepancies. The defaults are 1.0, so reduce the factor for the faster motor until a symmetrical sweep command drives the robot straight on flat ground.

It is expected that the ADC is used to monitor the battery level, but can be disabled if this is not the case.

Using simple outputs to control cutter relays is not recommended on the NodeMCU ESP8266 due to the erratic behaviour at boot time. I2C relays are preferred. If the I2C bus is not required it can be disabled.

Test Client

There is a simple Test Client python program in the clients folder. Once you have a mower device connected to the network, with an ip address,