OpenESL

Source

Open firmware for e-paper shelf labels

OpenESL runs on SoluM ZBS243 tags (2.9" and 1.54", black and white; the 2.9" with red is experimental) and an ESP32 access point: one ESP32-C6 board to start, or an ESP32-S3 with a C6 as its radio for up to about 1000 tags. The access point is a plain HTTP API: any software can put text on a tag by its MAC, and the AP sends it to the tag over 802.15.4 radio. This page has the tools to design the labels and to put the firmware on the hardware, all in the browser.

Design labels

Lay out text, inverted fields, lines and boxes for each tag model, with a preview drawn by the AP's own code. Save the layout file for the AP.

Open the designer

Flash a tag

Put the OpenESL firmware on a tag in the jig with a ZBS_Flasher. The stock firmware is backed up first and kept in this browser.

Open the tag flasher

Flash the access point

Put the AP firmware on an ESP32-C6, an ESP32-S3 + C6 or another supported board over USB. The page helps you choose.

Open the AP flasher

How it fits together

  1. Flash the AP on an ESP32-C6 (or an S3 + C6) and connect it to your computer or network. The Set up tab sets its WiFi and API token over USB.
  2. Flash the tags one by one in the jig. Each tag gets its MAC written to its info page and starts polling the AP.
  3. Design the layouts and upload the layout file to the AP with PUT /api/layouts/{model}. The AP draws each tag's screen from it and sends the image over the radio.
  4. Send content from your own software with PUT /api/tags/{mac}, naming a layout and its fields (see API).
  5. Keep it running: GET /api/health lists the tags that need attention, and a webhook posts the same report when it changes; "at" schedules prices for a given time; POST /api/ota updates the AP's firmware without a cable, keeping its stored tags; esl-client tag-ota sends new tag firmware to the tags over the radio; esl-client log logs a long-term test; esl-client backup and restore move the stored tags, layout files and settings to a file and onto another AP.

What you need

Setting up and running the AP: the wiki. API documentation: the API tab. Source and the radio protocol: github.com/mathiasbk/openesl.

The AP's limits for this layout

Preview with

Send to your AP

How is your AP connected?

Start the bridge in tools/esl-client on this computer: python3 tools/esl-client/esl_client.py --url http://<AP's address> --token <token> serve, then connect to http://localhost:8080. A page on https may only call the bridge, not the AP itself.

New from template for the 2.9"

Layout file (JSON)

Edits here change the design at once.

Upload with PUT /api/layouts/2.9:


    
  


  
  

    

      
    
      
    
      
    
        
        
        
      
    
      
     Each tag goes through the same steps as tools/flash-tui: MAC, a backup of the whole flash before anything is erased, the MAC to the info page if needed, then write and verify. The info page is never erased.
    
    
    
    
    
      
    
        
    
          
    
            
    Backups in this browser 
    
            
    The tags' own firmware, stored before the first flash. It stays in this browser until you clear the site's data, so export it and keep it somewhere safe. The barcode comes from the tag; you can also type or scan it.
    
          
    
          
    
            
            
          
    
        
    
        
    
          
    MACModelStoredBarcodeFiles
    
        
    
        
    
      
    
    
    
  
    

  
  
  
    
    
    
      
      
      
      
      
      
        
        
        
      
      
      
       Other ways to flash
      
    
      
  
      

  
  
      
    
    
    
      
      
      AP dashboard
      
      
      The AP's state and every tag, read from its API and refreshed every 10 seconds. Connect to the AP with a USB cable (Chrome or Edge on a computer). Over WiFi, open the same dashboard on the AP itself: http://openesl.local/dashboard (or the AP's IP address). A page on the web may not call an AP on your network, so for WiFi there is the AP's own page, or for developers the bridge in tools/esl-client (esl_client.py --url http://openesl.local --token <token> serve, then connect to http://localhost:8080).
      
      
      
        
        
        
        
        
        
      
      
      
      
    
      

    
  
      

  
  
      
    
      
      
      WiFi and API token over USB
      
      
      With the AP plugged into this computer, its WiFi and API token can be set from here, without its setup network. Chrome or Edge on a computer is needed (Web Serial). Close anything else that has the AP's port open first, such as esl_client.py ... serve: only one program can use it.
      
      
      
      
        
        
      
      
      
      
      
      
      Leave the network empty to change only the token, or the token empty to keep it. "Name" is the AP's name on the network: what your router lists, and http://NAME.local/. The token cannot be read back from the AP, so keep a copy. Opening the port can restart the AP; the page waits for it. From a terminal: esl_client.py --serial /dev/ttyACM0 wifi "Network" --password "..." --new-token "...".
      
    
      

    
      
      
      Getting an AP going
      
      
        
        
      1. Flash it on the Flash AP tab. Its last step gives the AP your WiFi and an API token over the same cable. More: Flashing the AP.
        2. 
        
      2. No cable? An AP with no WiFi saved opens an open network openesl-XXXX. Join it from a phone and fill in the form that opens (or go to http://192.168.4.1/setup). More: WiFi and API token.
        3. 
        
      3. Keep a copy of the token. Every API request needs it, and the AP never shows it again. Lost it? Set a new one over USB above: no old token is needed. More: The API token.
        4. 
        
      4. Open it at http://openesl-xxxx.local/dashboard, or at the IP your router gave it. More: Dashboard.
        5. 
        
      5. Keep it running: send content, watch its health, update it and back it up.
        6. 
      
      
      
      Stuck? See Troubleshooting. Developers: ap/README.md has menuconfig and how the AP stores things, and the API tab every call.
      
    
      
  
      

  
  
      
    
      The AP's HTTP API, from docs/openapi.yaml. To send test requests to your AP from here, run python3 tools/esl-client/esl_client.py --serial /dev/ttyACM0 serve on the computer the AP is plugged into (or --url http://openesl.local --token <token> serve over WiFi). Open on its own page.