OVMS3-idf/README.md

83 lines
3.8 KiB
Markdown
Raw Normal View History

2016-10-25 19:28:42 +00:00
# Using Espressif IoT Development Framework with the ESP32
2016-08-17 15:08:22 +00:00
2016-10-25 19:28:42 +00:00
[![alt text](https://readthedocs.org/projects/docs/badge/?version=latest "Documentation Status")](http://esp-idf.readthedocs.io/en/latest/?badge=latest)
2016-10-23 20:12:34 +00:00
2016-10-25 19:28:42 +00:00
# Setting Up ESP-IDF
In the [docs](docs) directory you will find per-platform setup guides:
* [Windows Setup Guide](docs/windows-setup.rst)
* [Mac OS Setup Guide](docs/macos-setup.rst)
* [Linux Setup Guide](docs/linux-setup.rst)
2016-10-25 19:28:42 +00:00
# Finding A Project
2016-10-25 19:28:42 +00:00
As well as the [esp-idf-template](https://github.com/espressif/esp-idf-template) project mentioned in the setup guide, esp-idf comes with some example projects in the [examples](examples) directory.
Once you've found the project you want to work with, change to its directory and you can configure and build it:
2016-08-17 15:08:22 +00:00
2016-10-25 19:28:42 +00:00
# Configuring your project
2016-08-17 15:08:22 +00:00
`make menuconfig`
2016-10-25 19:28:42 +00:00
# Compiling your project
2016-08-17 15:08:22 +00:00
`make all`
2016-08-17 15:08:22 +00:00
... will compile app, bootloader and generate a partition table based on the config.
2016-08-17 15:08:22 +00:00
2016-10-25 19:28:42 +00:00
# Flashing your project
2016-08-17 15:08:22 +00:00
When `make all` finishes, it will print a command line to use esptool.py to flash the chip. However you can also do this from make by running:
2016-08-17 15:08:22 +00:00
`make flash`
2016-08-17 15:08:22 +00:00
This will flash the entire project (app, bootloader and partition table) to a new chip. The settings for serial port flashing can be configured with `make menuconfig`.
2016-08-17 15:08:22 +00:00
You don't need to run `make all` before running `make flash`, `make flash` will automatically rebuild anything which needs it.
2016-08-17 15:08:22 +00:00
2016-10-25 19:28:42 +00:00
# Compiling & Flashing Just the App
2016-08-17 15:08:22 +00:00
After the initial flash, you may just want to build and flash just your app, not the bootloader and partition table:
* `make app` - build just the app.
* `make app-flash` - flash just the app.
`make app-flash` will automatically rebuild the app if it needs it.
(There's no downside to reflashing the bootloader and partition table each time, if they haven't changed.)
2016-08-17 15:08:22 +00:00
2016-10-25 19:28:42 +00:00
# The Partition Table
2016-08-17 15:08:22 +00:00
Once you've compiled your project, the "build" directory will contain a binary file with a name like "my_app.bin". This is an ESP32 image binary that can be loaded by the bootloader.
A single ESP32's flash can contain multiple apps, as well as many different kinds of data (calibration data, filesystems, parameter storage, etc). For this reason a partition table is flashed to offset 0x4000 in the flash.
Each entry in the partition table has a name (label), type (app, data, or something else), subtype and the offset in flash where the partition is loaded.
The simplest way to use the partition table is to `make menuconfig` and choose one of the simple predefined partition tables:
* "Single factory app, no OTA"
* "Factory app, two OTA definitions"
In both cases the factory app is flashed at offset 0x10000. If you `make partition_table` then it will print a summary of the partition table.
2016-10-25 19:28:42 +00:00
For more details about partition tables and how to create custom variations, view the `docs/partition-tables.rst` file.
# Erasing Flash
The `make flash` target does not erase the entire flash contents. However it is sometimes useful to set the device back to a totally erased state, particularly when making partition table changes or OTA app updates. To erase the entire flash, run `make erase_flash`.
This can be combined with other targets, ie `make erase_flash flash` will erase everything and then re-flash the new app, bootloader and partition table.
2016-10-25 19:28:42 +00:00
# Resources
2016-10-25 19:28:42 +00:00
* The [docs directory of the esp-idf repository](docs) contains source of [esp-idf](http://esp-idf.readthedocs.io/) documentation.
* The [esp32.com forum](http://esp32.com/) is a place to ask questions and find community resources.
* [Check the Issues section on github](https://github.com/espressif/esp-idf/issues) if you find a bug or have a feature request. Please check existing Issues before opening a new one.
2016-10-25 19:28:42 +00:00
* If you're interested in contributing to esp-idf, please check the [Contributions Guide](http://esp-idf.readthedocs.io/en/latest/contributing.html>).
2016-10-23 20:59:53 +00:00