README

   1 apeos is a project with goal of providing text shell and server (as in
   2 socket bind()) experience on esp-32.
   3
   4 apeos is a portmanteau of ape, a class of animal species humans are
   5 part of, and os, for operating system. Whether one can write like Shak
   6 on apeos probably depends on whether shis tail can be easily hidden
   7 with a dress :)
   8
   9 Building
  10 ========
  11
  12 Have esp-idf v3.0 (git commit 6698be57c80eaa968aca40d12d17479c06e75ae8
  13 is known to work) setup. This prerequisite also brings xtensa-32 gcc
  14 toolchain. For x86 and x86_64 hosts, prebuilt gcc/binutils/glibc
  15 toolchains targeting xtensa-32 ISA are available. Building the cross
  16 toolchain from source for arm32, aarch64 or other host architectures
  17 is achieved via crosstool-NG from xtensa specific git branch.
  18
  19 The build process uses GNU make.
  20
  21 Build everything:
  22
  23 make
  24
  25 If host machine has more than one CPU (in single socket or not),
  26 supply -j option to make. E.g. "make -j4" to use four CPU cores.
  27
  28 When build finishes, a command-line suggestion is printed. This
  29 command-line can be used to write the binary to flash memory storage
  30 attached to esp32 via SPI.
  31
  32 Interaction with esp32 chip is achieved through esptool.py, a good
  33 tool useful on systems that can interpret python language.
  34
  35 Beware that flash storage memory is subject to wearing and flashing
  36 any particular memory area multiple times will ultimatly lead to flash
  37 area misfunction. Thus use of download mode of esp32 chip is
  38 also anticipated for transfering versions of apeos to target computer
  39 without the abovementioned storage weakness.
  40
  41 Once written to flash storage memory, apeos operation state is
  42 verified by the "apeos booting" ASCII byte stream signature appearing
  43 on esp32 chip hardware reset via EN pin.
  44
  45 After a newline ('\n'), another line describing environment apeos is
  46 running is printed.
  47
  48 This output, and also availability for input is best achieved via
  49 software emulators of hardware terminals and a program to interconnect
  50 UART tty devices. In some cases programs implement both.
  51
  52 Some software terminal implemetations are:
  53  * linux framebuffer
  54  * tmux
  55  * GNU screen
  56  * miniterm
  57  * X11 xterm
  58  * GNOME/KDE/etc terminal emulators
  59  * PuTTY for Windows
  60  * Windows command-line subsystem
  61
  62 Some interconnect implementations are:
  63  * cu (linux port available [1])
  64  * esptool.py
  65  * PuTTY for Windows
  66  * GNU screen
  67  * miniterm
  68
  69 The esp-idf project use of esptool_py is currently configured for
  70 /dev/ttyUSB0 device of usb-to-serial module that is connected to UART0
  71 of esp32 chip.
  72
  73 When connecting esp32 chip through USB with goal of not damaging the
  74 chip, some points can be checked:
  75  * Unless you are connecting usb-to-serial with CMOS 3.3V interface,
  76    make sure you understand how the interconnection operates.
  77  * If you use a dedicated power supply for esp32, which allows more
  78    power than USB bus can deliver, use galvanical isolation of UART
  79    signal. 6n137 optrons (optocouplers) are an option rated at 10+
  80    megabaud and may be available for you in 5V and 3.3V VCC variants.
  81    As 6n137 has open collector output, its digital data path can
  82    interoperate at esp32's 3.3V even when 6n137 VCC is 5V.
  83
  84 [1] a port of openbsd cu(1) to Linux: http://github.com/nedko/cu.git