How to describe the device you want
The whole platform is one input box. The sentence you type there is its only source of what you want — which probably makes this the most worthwhile page of the ten.
At a glance
| What it can read from your words | What device you want, how you want to interact with it, what hardware you already have, what counts as done, what accuracy you need |
|---|---|
| What it cannot read | How your wiring actually looks, the exact revision of your board, how strong your Wi-Fi is, your budget (unless you say so) |
| Limit per message | 8000 characters in a project chat; 4000 in the homepage chat |
| Files you can send | The input box takes images and text-type files (png jpg webp gif log txt csv json md, plus source and config files), 10MB each, at most 5 per message and 20MB per message in total. The input box takes neither pdf nor zip — send those to the Files pane instead (25MB per file); rar, 7z and tar are taken by neither channel |
| Language of the reply | Follows the language of your message, not the interface language. It tells apart Chinese, English, Japanese and Korean |
Start with the difference between two messages
The same idea, said two ways, gets completely different results.
Vague:
All it can do is guess: guess infrared or ultrasonic, guess whether you want a display, guess whether you want it on the network, guess what accuracy you need. Every wrong guess costs you another round of edits.
Clear:
Why this one works: it names the board and the module, so nothing has to be guessed out of dozens of candidate part numbers; it gives two pins and how the module is powered, which saves a round trip; and saying "no display" keeps an extra screen — and the several pins that screen would take — out of the plan.
Say these five things
You do not have to say all of it at once, but the more you say, the fewer rounds of revision.
| 1 · What it does | The job the device carries out. "Measure how far away the obstacle in front is", "take a photo on a button press", "show the time on a screen". |
|---|---|
| 2 · How you interact with it | A display, a web page, or the serial port. |
| 3 · What you already have | The most important one. Which board, which modules — give the part numbers straight out. |
| 4 · What counts as done | "The serial port prints the distance" and "a live chart on my phone" are two different amounts of work. |
| 5 · Accuracy and range | What accuracy, over what range. |
Item 3 is worth the most. If you do not say what you have, it can only plan for the most common case, and then you find the board in the plan is one you do not own, while the board you own goes unused. Say it at the start and you save a whole round trip.
A library of examples
Every one below is complete and can be copied and pasted as a whole. Pick one and edit it into your own situation.
Blinking and output
Why this one works: "confirm the whole chain works" is the convention in this field — with a new board, flash a blinker first and clear all five links in one go: board, cable, driver, browser, flashing. Later, when a real project misbehaves, you know those five are not the cause.
Why this one works: "active-low" is the line beginners often do not know to say. Leave it out and the code closes the relay on a high level; on the bench the behaviour comes out inverted, and nothing in the code shows where the error is.
Reading sensors
Why this one works: "print a line even when there is no reading" — an ultrasonic module gets no echo back from open space or soft fabric all the time. Skip those silently and the serial port goes intermittent for no visible reason, and you have no way to tell a missed reading from a dead program.
Why this one works: the same part number can sit at a different address on a different module. Having it scan at startup is faster than looking it up, and that scan output stays useful for troubleshooting later.
Buttons and input
Why this one works: "no external resistor" tells it to enable the chip's internal pull-up. Without that line, the code may assume you have a resistor outside, and the button fires at random.
Building a web page
Why this one works: "keep it plain" holds this round to the smallest scope — first the page opens and the number moves; styling and charts are the next round. Ask for too much at once and, when something breaks, you cannot tell the network from the page.
Getting on the network
Why this one works: both lines save you work later. "Print the IP to the serial port" — otherwise you have no idea what address to type into the browser. "Say which kind of failure it was" costs almost nothing and pays a lot: Wi-Fi not connecting is the most common problem there is, and default code tends to print only "connect failed", which does nothing for you.
Putting it together
Why this one works: "keep the serial output running when the network drops" — network code is easy to write as blocking, and then a dropped connection makes the whole device look like it has crashed. Saying so up front avoids a problem that is hard to locate on your own. At this point you have the example project this documentation has been using all along.
Write in the constraints it cannot guess
The lines below are things a beginner has no way of knowing, and they change the result. Where one matches your situation, add it to your description.
| Add this line | Why |
|---|---|
My module is a 3.3V one, do not design for 5V | The wrong level means no reading at best and a burnt-out module at worst |
Do not use GPIO6 through GPIO11 | On a classic ESP32 those pins are wired to the flash chip; take them and the board does not come up at all |
No delay longer than 50 ms in the main loop | A long delay makes the button unresponsive and the network drop, and the symptom looks like "it froze" |
Use 115200 for the serial baud rate | Unspecified, it has to be guessed, and a wrong guess makes the whole log unreadable |
At startup, print the chip model, the flash size and the current pin configuration | For any problem later, the first thing anyone asks is "paste your boot log". Having it built in is a dashboard you gave yourself |
Sending schematics and datasheets
When typing cannot get it across, give it the file. There are two channels and they do completely different things — do not mix them up.
| Workspace assets | A temporary attachment in the chat box | |
|---|---|---|
| How to send it | Switch to the Files pane and upload | Paste or drag it straight into the input box |
| How long it lives | Stays; it is engineering material belonging to this project | Good for this one turn of the conversation, and not kept after that |
| Can you reference it again | Yes. Type @ in the input box and the asset list drops down; it searches file names and tags, and what it finally matches on is the file name | No |
| Does it travel with the project | Yes (in backups, in a release, and when someone clones it) | No |
| What belongs here | Schematics, datasheets, module documentation; 25MB per file, so a full SDK archive usually will not fit | A one-off screenshot of an error, a chunk of log |
A common disappointment: you paste the schematic in as a temporary attachment, and two turns later it has "forgotten" it. That is not a bad memory — a temporary attachment was only ever good for one turn. Send schematics and datasheets to the Files pane.
After uploading a file, add a line about what to do with it
Drag a file in and say nothing, and it does not know what you want done with it. The interface asks you for that line as well.
Log too long to paste? A single project-chat message caps at 8000 characters, but you do not have to save a file yourself — paste the log straight into the input box, and a paste that goes over the limit is turned, whole, into a pasted-….log attachment. Then write a line such as "this is the serial output after flashing, help me work out why it keeps rebooting".
Any language works
Write in Chinese and it answers in Chinese; ask in English and it answers in English; Japanese and Korean the same. It follows the language of your message, not the language of the interface. So with the interface in English and your question in Chinese, the reply still comes back in Chinese.
The four it tells apart right now are Chinese, English, Japanese and Korean. Other languages written in the Latin alphabet (Spanish, French and so on) are treated as English.
If you come from software development
Think of this input box as a compiler from intent to engineering change, rather than as a chatbot. Every turn it does this: read what you said → read the current project's hardware facts → decide whether the code has to change → actually change it and build it.
So how precise your description is sets the quality of the output, exactly as with writing an issue: state all three of expected behaviour, real constraints, acceptance criteria and the round trips drop. The difference is that it cannot git diff your desk — your wiring, your board revision, it sees none of it, and can only go on what you say.
Common questions
The plan it gave me is not what I want — now what?
Say what is wrong with it; there is no need to describe the whole thing again. "I do not need the display in this plan, take it out", "switch to the ESP32-C3 I have" — it edits the existing plan.
Can I ask it to use a specific library?
Yes, name it. Use esp_http_server for the HTTP server, no third-party frameworks. Unnamed, it picks a common one itself.
Is it better to say everything at once?
No. Get the smallest version working, verify it, then add to it. Describe ten features in one go and, when something breaks, you cannot tell which piece broke, and every edit costs another build. The convention in this field is blink first, then read a sensor, then get on the network.