From cf3bbece77468e2d0eb74c2f23118e2dde23e64b Mon Sep 17 00:00:00 2001 From: Nedko Arnaudov Date: Sun, 8 Jul 2018 16:22:52 +0300 Subject: [PATCH] Update and extend the README --- README | 66 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 56 insertions(+), 10 deletions(-) diff --git a/README b/README index e731476..c152235 100644 --- a/README +++ b/README @@ -9,8 +9,12 @@ with a dress :) Building ======== -Have esp-idf v3.0 (git commit 6698be57c80eaa968aca40d12d17479c06e75ae8) -setup. This prerequisite also brings xtensa-32 gcc toolchain. +Have esp-idf v3.0 (git commit 6698be57c80eaa968aca40d12d17479c06e75ae8 +is known to work) setup. This prerequisite also brings xtensa-32 gcc +toolchain. For x86 and x86_64 hosts, prebuilt gcc/binutils/glibc +toolchains targeting xtensa-32 ISA are available. Building the cross +toolchain from source for arm32, aarch64 or other host architectures +is achieved via crosstool-NG from xtensa specific git branch. The build process uses GNU make. @@ -21,18 +25,60 @@ make If host machine has more than one CPU (in single socket or not), supply -j option to make. E.g. "make -j4" to use four CPU cores. -Flash the built binary to esp-32 flash storage: +When build finishes, a command-line suggestion is printed. This +command-line can be used to write the binary to flash memory storage +attached to esp32 via SPI. -make flash +Interaction with esp32 chip is achieved through esptool.py, a good +tool useful on systems that can interpret python language. -Attach terminal emulator to UART0: +Beware that flash storage memory is subject to wearing and flashing +any particular memory area multiple times will ultimatly lead to flash +area misfunction. Thus use of download mode of esp32 chip is +also anticipated for transfering versions of apeos to target computer +without the abovementioned storage weakness. -make monitor +Once written to flash storage memory, apeos operation state is +verified by the "apeos booting" ASCII byte stream signature appearing +on esp32 chip hardware reset via EN pin. -Alternatively, use the cu program [1] or similar program for -attaching terminal emulator to UART0. +After a newline ('\n'), another line describing environment apeos is +running is printed. -The project use of esptool_py is currently configured for -/dev/ttyUSB0 device of usb-to-serial module that connects to UART0. +This output, and also availability for input is best achieved via +software emulators of hardware terminals and a program to interconnect +UART tty devices. In some cases programs implement both. + +Some software terminal implemetations are: + * linux framebuffer + * tmux + * GNU screen + * miniterm + * X11 xterm + * GNOME/KDE/etc terminal emulators + * PuTTY for Windows + * Windows command-line subsystem + +Some interconnect implementations are: + * cu (linux port available [1]) + * esptool.py + * PuTTY for Windows + * GNU screen + * miniterm + +The esp-idf project use of esptool_py is currently configured for +/dev/ttyUSB0 device of usb-to-serial module that is connected to UART0 +of esp32 chip. + +When connecting esp32 chip through USB with goal of not damaging the +chip, some points can be checked: + * Unless you are connecting usb-to-serial with CMOS 3.3V interface, + make sure you understand how the interconnection operates. + * If you use a dedicated power supply for esp32, which allows more + power than USB bus can deliver, use galvanical isolation of UART + signal. 6n137 optrons (optocouplers) are an option rated at 10+ + megabaud and may be available for you in 5V and 3.3V VCC variants. + As 6n137 has open collector output, its digital data path can + interoperate at esp32's 3.3V even when 6n137 VCC is 5V. [1] a port of openbsd cu(1) to Linux: http://github.com/nedko/cu.git -- 2.11.4.GIT