Getting Started - tjhorner/wifi-desk-controller Wiki

If you don't like reading walls of text and know what you are doing, see Quick Start.

Prefer to watch a video instead? See the quick start video.

Did you order a kit? See the Kit Soldering Instructions.

Step 1: Choose Your Ecosystem

Since this is open hardware, you can choose to flash whatever firmware you want, and therefore use any ecosystem you'd like. However, you'll have the best experience with Home Assistant + ESPHome, since ready-made configurations and components are officially provided. If you're using something other than Home Assistant, you're still in luck! There are guides (soon) for other platforms, though they are considered unofficial and community-supported.

The rest of this page will assume you are using Home Assistant and will walk you through either flashing the stock ESPHome-based firmware, or building your own config with the official ESPHome component for this project.

Step 2: Flash Firmware

Note: If you ordered your board with pre-flashed firmware, you don't need to complete this step. Just connect it to WiFi as described below.

Pre-Flashed Firmware Setup
  1. Plug the board into power with the micro USB cable.
  2. Connect your phone/laptop to the ad-hoc network.
    • SSID: Standing Desk Controller
    • Password: hunter2hunter2
  3. Your device should automatically navigate to the setup page, but if it doesn't, manually go to in a browser.
  4. Select your WiFi network and enter credentials.
  5. Skip to step 3 of this guide.

Since there's no firmware on the board by default, you will need to install some. There are two ways you can do this: flash the stock firmware, or use ESPHome to make your own config.

Option 1: Stock Firmware

The stock firmware is based on ESPHome, pre-compiled, and easy to flash. It's a great option if you don't have ESPHome readily-installed on your machine, but provides less flexibility than writing your own config. If you use the stock firmware, you get these features out of the box:

  • Native ESPHome API
    • This allows Home Assistant to natively adopt the device and add it as an integration, without any configuration
  • Web Server
    • Provides a web UI and HTTP API; useful for writing your own integrations or operating headless
    • API Documentation
  • OTA Updates
    • If you ever decide to write your own ESPHome config, you can easily update the board with your new firmware

You can flash the stock firmware to your board here. If you need to connect to an MQTT broker or require further customization, you will need to write your own config.

Option 2: ESPHome Config

Writing your own ESPHome config lets you customize the firmware to meet your needs. You can find a tool which generates a boilerplate config here. You can use it as the basis for your own config, or learn how it works at this repo.

Step 3: Plug it in

Once the firmware is flashed, you can plug the device into your desk.

If you are using a Fully Jarvis desk, please read Jarvis Power Issue.

First, plug an RJ45 (standard ethernet) cable into the keypad that came with your desk (which jack you plug it into does not matter). Then, with a second cable, plug the device into the desk itself. Your desk may briefly lower or raise when plugged in; this is normal during first startup and won't happen again unless power is lost.

If your desk's control box cannot supply enough current for the board, you may need to keep the micro USB cable plugged in during usage. See this troubleshooting section for more information.

Step 4: Add to Home Assistant

Home Assistant should automatically discover the device and offer to add it as an integration. If it doesn't, go to Integrations in Settings, then add an ESPHome integration -- the IP address should be standing-desk.local (or whatever your local domain is).

You can also add the Home Assistant Card to your dashboard for easy control.

Step 5: Questions?

If you have additional questions or just need help setting the board up with your home automation system, first check Troubleshooting. If your problem is not listed there, email me and I'll do my best to help out! My email is [email protected].

⚠️ ** Fallback** ⚠️