apeos is a project with goal of providing text shell and server (as in
socket bind()) experience on esp-32.

apeos is a portmanteau of ape, a class of animal species humans are
part of, and os, for operating system. Whether one can write like Shak
on apeos probably depends on whether shis tail can be easily hidden
with a dress :)

Building
========

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.

Build everything:

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.

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.

Interaction with esp32 chip is achieved through esptool.py, a good
tool useful on systems that can interpret python language.

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.

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.

After a newline ('\n'), another line describing environment apeos is
running is printed.

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