diff --git a/.gitignore b/.gitignore index 581028ed14..f112376880 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,9 @@ out # generated documentation docs/api +docs/build +docs/source/_inc +*.pyc # dev tools, editors, etc. language.settings.xml diff --git a/.gitmodules b/.gitmodules index f910ca0dea..ca4f3c3fd3 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,7 +1,3 @@ -[submodule "Sming.wiki"] - path = docs/wiki - url = https://github.com/SmingHub/Sming.wiki.git - ignore = dirty [submodule "spiffs"] path = Sming/Components/spiffs/spiffs url = https://github.com/pellepl/spiffs.git diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000000..801ca5ff31 --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,22 @@ +# .readthedocs.yml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Optionally build your docs in additional formats such as PDF and ePub +formats: + - htmlzip +# - pdf + +# Optionally set the version of Python and requirements required to build your docs +python: + version: 3.7 + install: + - requirements: docs/requirements.txt + +# We pull in and patch submodules separately +submodules: + exclude: all + recursive: false diff --git a/.travis.yml b/.travis.yml index a9bafe9cfa..bf22bed09e 100644 --- a/.travis.yml +++ b/.travis.yml @@ -14,6 +14,10 @@ jobs: - clang-format-6.0 - gcc-multilib - g++-multilib + - doxygen + - python3-sphinx + - python3-pip + - python3-setuptools env: SMING_ARCH=Host - stage: build diff --git a/.travis/build.sh b/.travis/build.sh index f7f05c0d7f..22f4f9e1ce 100755 --- a/.travis/build.sh +++ b/.travis/build.sh @@ -58,6 +58,11 @@ if [ "$TRAVIS_BUILD_STAGE_NAME" == "Test" ]; then # Build and run tests export SMING_TARGET_OPTIONS='--flashfile=$(FLASH_BIN) --flashsize=$(SPI_SIZE)' $MAKE_PARALLEL tests + + # Build the documentation + mv $SMING_PROJECTS_DIR/samples .. + mv $SMING_PROJECTS_DIR/tests .. + make docs V=1 else $MAKE_PARALLEL samples make clean samples-clean diff --git a/.travis/install.sh b/.travis/install.sh index 46055b1d47..a9baf4e839 100755 --- a/.travis/install.sh +++ b/.travis/install.sh @@ -3,6 +3,7 @@ set -ex # exit with nonzero exit code if anything fails if [ "$TRAVIS_BUILD_STAGE_NAME" == "Test" ]; then sudo update-alternatives --install /usr/bin/clang-format clang-format /usr/bin/clang-format-6.0 100 + pip3 install -r $TRAVIS_BUILD_DIR/docs/requirements.txt fi if [ "$SMING_ARCH" == "Esp8266" ]; then diff --git a/Sming/Arch/Esp8266/Components/axtls-8266/README.rst b/Sming/Arch/Esp8266/Components/axtls-8266/README.rst new file mode 100644 index 0000000000..ca241a1381 --- /dev/null +++ b/Sming/Arch/Esp8266/Components/axtls-8266/README.rst @@ -0,0 +1,4 @@ +AXTLS 8266 +========== + +SSL support using the AXTLS library diff --git a/Sming/Arch/Esp8266/Components/axtls-8266/component.mk b/Sming/Arch/Esp8266/Components/axtls-8266/component.mk index 4dbbf8778f..6d64474925 100644 --- a/Sming/Arch/Esp8266/Components/axtls-8266/component.mk +++ b/Sming/Arch/Esp8266/Components/axtls-8266/component.mk @@ -3,6 +3,8 @@ SSL_DEBUG ?= 0 COMPONENT_SUBMODULES := axtls-8266 +COMPONENT_DEPENDS := esp8266 + COMPONENT_SRCDIRS := \ axtls-8266/compat \ axtls-8266/replacements \ diff --git a/Sming/Arch/Esp8266/Components/custom_heap/README.rst b/Sming/Arch/Esp8266/Components/custom_heap/README.rst new file mode 100644 index 0000000000..e05826f3b7 --- /dev/null +++ b/Sming/Arch/Esp8266/Components/custom_heap/README.rst @@ -0,0 +1,7 @@ +Custom Heap +=========== + +Provides an alternative heap memory manager using UMM Malloc. + +.. warning:: + Do not enable custom heap allocation and -mforce-l32 compiler flag at the same time. diff --git a/Sming/Arch/Esp8266/Components/custom_heap/component.mk b/Sming/Arch/Esp8266/Components/custom_heap/component.mk index 2cf21869a5..944adf48d3 100644 --- a/Sming/Arch/Esp8266/Components/custom_heap/component.mk +++ b/Sming/Arch/Esp8266/Components/custom_heap/component.mk @@ -5,6 +5,8 @@ COMPONENT_SRCDIRS := COMPONENT_SRCFILES := heap.c umm_malloc/src/umm_malloc.c COMPONENT_INCDIRS := umm_malloc/src umm_malloc/includes/c-helper-macros +COMPONENT_DEPENDS := esp8266 + LIBMAIN = mainmm LIBMAIN_SRC = $(COMPONENT_LIBDIR)/libmainmm.a COMPONENT_TARGETS += $(LIBMAIN_SRC) diff --git a/Sming/Arch/Esp8266/Components/driver/README.rst b/Sming/Arch/Esp8266/Components/driver/README.rst new file mode 100644 index 0000000000..c1d6246970 --- /dev/null +++ b/Sming/Arch/Esp8266/Components/driver/README.rst @@ -0,0 +1,7 @@ +Esp8266 Drivers +=============== + +Provides low-level peripheral support classes. + +* UART: Custom asynchronous driver +* PWM: Common header for PWM support diff --git a/Sming/Arch/Esp8266/Components/driver/component.mk b/Sming/Arch/Esp8266/Components/driver/component.mk new file mode 100644 index 0000000000..5fee1d9bc1 --- /dev/null +++ b/Sming/Arch/Esp8266/Components/driver/component.mk @@ -0,0 +1 @@ +COMPONENT_DEPENDS := esp8266 diff --git a/Sming/Arch/Esp8266/Components/esp-lwip/README.rst b/Sming/Arch/Esp8266/Components/esp-lwip/README.rst new file mode 100644 index 0000000000..d33c391223 --- /dev/null +++ b/Sming/Arch/Esp8266/Components/esp-lwip/README.rst @@ -0,0 +1,6 @@ +Esp8266 LWIP (Espressif) +======================== + +The Espressif SDK provides a default version of LWIP, enabled by using this Component. + +See :envvar:`ENABLE_CUSTOM_LWIP`. diff --git a/Sming/Arch/Esp8266/Components/esp-lwip/component.mk b/Sming/Arch/Esp8266/Components/esp-lwip/component.mk index bee0acf346..dda9654c9f 100644 --- a/Sming/Arch/Esp8266/Components/esp-lwip/component.mk +++ b/Sming/Arch/Esp8266/Components/esp-lwip/component.mk @@ -1,5 +1,7 @@ COMPONENT_LIBNAME := +COMPONENT_DEPENDS := esp8266 + COMPONENT_INCDIRS += . ifeq ($(SMING_RELEASE),1) diff --git a/Sming/Arch/Esp8266/Components/esp-open-lwip/README.rst b/Sming/Arch/Esp8266/Components/esp-open-lwip/README.rst new file mode 100644 index 0000000000..09943654ce --- /dev/null +++ b/Sming/Arch/Esp8266/Components/esp-open-lwip/README.rst @@ -0,0 +1,16 @@ +Esp8266 Open LWIP (version 1) +============================= + +This Component provides the default Sming LWIP stack, which uses less RAM than the Espressif version. + +See :envvar:`ENABLE_CUSTOM_LWIP`. + +.. envvar:: ENABLE_LWIPDEBUG + + 0 (default) + Standard build + 1 + Enable debugging output + + You can increase debugging for certain areas by modifying debug options in ``esp-open-lwip/include/lwipopts.h``. + diff --git a/Sming/Arch/Esp8266/Components/esp-open-lwip/component.mk b/Sming/Arch/Esp8266/Components/esp-open-lwip/component.mk index 37b4b926aa..39a1829084 100644 --- a/Sming/Arch/Esp8266/Components/esp-open-lwip/component.mk +++ b/Sming/Arch/Esp8266/Components/esp-open-lwip/component.mk @@ -2,6 +2,8 @@ COMPONENT_VARS := ENABLE_LWIPDEBUG ENABLE_ESPCONN ENABLE_LWIPDEBUG ?= 0 ENABLE_ESPCONN ?= 0 +COMPONENT_DEPENDS := esp8266 + COMPONENT_CFLAGS := \ -DPBUF_RSV_FOR_WLAN \ -DEBUF_LWIP -DLWIP_OPEN_SRC \ diff --git a/Sming/Arch/Esp8266/Components/esp8266/README.rst b/Sming/Arch/Esp8266/Components/esp8266/README.rst new file mode 100644 index 0000000000..49051b52dc --- /dev/null +++ b/Sming/Arch/Esp8266/Components/esp8266/README.rst @@ -0,0 +1,32 @@ +Esp8266 Core Component +====================== + +Contains startup code, crash handling and additional Esp8266-specific +support code. Sming may be built using a pre-installed SDK, or by using +the current version 3 SDK as a submodule. + +.. envvar:: SDK_BASE + + Points to the location of the Espressif Non-OS SDK. To use the Espressif version 3 SDK, you need + only set this variable to point at the Sming repository (:envvar:`SMING_HOME`). The actual location + will be subsituted by the build system and the SDK pulled in via GIT. + + So for Windows you need to do: + + :: + + set SDK_BASE=%SMING_HOME% + + For Linux (bash): + + :: + + export SDK_BASE="$SMING_HOME" + + If you change this value then your application and Sming must both be recompiled: + + :: + + make components-clean clean + make + diff --git a/Sming/Arch/Esp8266/Components/esp_wifi/README.rst b/Sming/Arch/Esp8266/Components/esp_wifi/README.rst new file mode 100644 index 0000000000..ece466ab31 --- /dev/null +++ b/Sming/Arch/Esp8266/Components/esp_wifi/README.rst @@ -0,0 +1,13 @@ +Esp8266 WiFi +============ + +All related libraries for WiFi support. Definitions are provided in the +Espressif Non-OS SDK. + +Options +------- + +.. envvar:: ENABLE_WPS + + Set to 1 to enable WiFi Protected Setup (WPS) + WPS is not enabled by default to preserve resources, and because there may be security implications which you should consider carefully. diff --git a/Sming/Arch/Esp8266/Components/esp_wifi/component.mk b/Sming/Arch/Esp8266/Components/esp_wifi/component.mk index e825d649ab..6d092020b9 100644 --- a/Sming/Arch/Esp8266/Components/esp_wifi/component.mk +++ b/Sming/Arch/Esp8266/Components/esp_wifi/component.mk @@ -1,5 +1,7 @@ COMPONENT_LIBNAME := +COMPONENT_DEPENDS := esp8266 + # => WPS COMPONENT_VARS := ENABLE_WPS ifeq ($(ENABLE_WPS), 1) diff --git a/Sming/Arch/Esp8266/Components/esptool/README.rst b/Sming/Arch/Esp8266/Components/esptool/README.rst new file mode 100644 index 0000000000..df11b055fa --- /dev/null +++ b/Sming/Arch/Esp8266/Components/esptool/README.rst @@ -0,0 +1,36 @@ +Esptool +======= + +This Component provides Espressif's tool for reading and writing firmware and other data to hardware. + +Options +------- + +.. envvar:: SPI_SPEED + + Clock speed for flash memory (20, 26, 40 or 80). Default is 40. + + +.. envvar:: SPI_MODE + + Flash memory operating mode (quot, dio, dout, qio). Default is qio. + + +.. envvar:: SPI_SIZE + + Size of flash memory chip (256KB, 512KB, 1MB, 2MB, 4MB). Default is 512K bytes. + + +.. envvar:: ESPTOOL + + Full path of esptool.py + + +.. envvar:: COM_PORT_ESPTOOL + + Port to use for flashing device. Default is :envvar:`COM_PORT`. + + +.. envvar:: COM_SPEED_ESPTOOL + + Baud rate to use for flashing device. Default is :envvar:`COM_SPEED`. diff --git a/Sming/Arch/Esp8266/Components/esptool/component.mk b/Sming/Arch/Esp8266/Components/esptool/component.mk index a3dec5d669..4828ea7f60 100644 --- a/Sming/Arch/Esp8266/Components/esptool/component.mk +++ b/Sming/Arch/Esp8266/Components/esptool/component.mk @@ -1,5 +1,7 @@ COMPONENT_LIBNAME := +COMPONENT_DEPENDS := esp8266 + CONFIG_VARS += SPI_SPEED SPI_MODE SPI_SIZE # SPI_SPEED = 40, 26, 20, 80 diff --git a/Sming/Arch/Esp8266/Components/fatfs/README.rst b/Sming/Arch/Esp8266/Components/fatfs/README.rst new file mode 100644 index 0000000000..0f85a7d7a7 --- /dev/null +++ b/Sming/Arch/Esp8266/Components/fatfs/README.rst @@ -0,0 +1,6 @@ +FAT Filing System +================= + +Required by the SDCard library. + +http://elm-chan.org/fsw/ff/00index_e.html diff --git a/Sming/Arch/Esp8266/Components/gdbstub/GdbPacket.h b/Sming/Arch/Esp8266/Components/gdbstub/GdbPacket.h index 83344ec3c9..3f511991ef 100644 --- a/Sming/Arch/Esp8266/Components/gdbstub/GdbPacket.h +++ b/Sming/Arch/Esp8266/Components/gdbstub/GdbPacket.h @@ -82,9 +82,9 @@ class GdbPacket /** @brief Encode a value as hex characters, LSB first * @param dst Location for output, will NOT be nul-terminated - * @param srcData Data bytes to encode + * @param src Data bytes to encode * @param size Size of source data in bytes - * @Note destination buffer must have enough space for (size * 2) chars + * @note destination buffer must have enough space for (size * 2) chars */ static void encodeHexBlock(char* dst, const void* src, size_t size); diff --git a/Sming/Arch/Esp8266/Components/gdbstub/README.rst b/Sming/Arch/Esp8266/Components/gdbstub/README.rst new file mode 100644 index 0000000000..7b9f975072 --- /dev/null +++ b/Sming/Arch/Esp8266/Components/gdbstub/README.rst @@ -0,0 +1,237 @@ +Esp8266 GDBSTUB for Sming +========================= + +Background +---------- + +This is a rewrite of gdbstub based on the +`esp8266 Arduino project `__. + +To use the GNU Debugger (GDB) with Sming requires your application to +include some code (``gdbstub``) which communicates via the serial port. +On the ESP8266 only UART0 may be used for this as UART1 is +transmit-only. + +The gdbstub code will only be built if you specify :c:macro:`ENABLE_GDB` +=1 when compiling your application. At startup, before your init() +function is called, it will claim UART0 so your application will be +unable to use it directly. Therefore, the default port for ``Serial`` +is changed to ``UART2``. + +UART2 is a ‘virtual’ serial port to enable serial communications to work +correctly when GDB-enabled. Read/write calls and serial callbacks are +handled via gdbstub. Baud rate changes affect UART0 directly. + +Note that ``target`` refers to the application being debugged, and +``host`` the development system running the GDB program. + +Refer to the official +`GDB documention `__ +for further details. + +GDB +--- + +This is the application which runs on your development system and talks +to ``gdbstub``. + +- Linux: A version of this should be available in + ``$ESP_HOME/xtensa-lx106-elf/bin/xtensa-lx106-elf-gdb`` + +- Windows: At time of writing, UDK doesn’t provide a GDB application + - Download and run the executable installer at `SysProgs `__ + + - Copy the + ``C:\SysGCC\esp8266\opt\xtensa-lx106-elf\bin\xtensa-lx106-elf-gdb.exe`` + to a suitable location. + +- Mac: ? + +Usage +----- + +- Configure gdbstub by editing ``gdbstub-cfg.h`` as required. You + can also configure the options by setting ::envvar:`USER_CFLAGS` in + your project’s ``component.mk`` file. e.g + ``USER_CFLAGS=-DGDBSTUB_BREAK_ON_INIT=0``. +- Optional: Add ``gdb_do_break()`` statements to your application. +- Run ``make clean``, then ``make ENABLE_GDB=1 flash`` to build and + flash the application with debugging enabled +- Run gdb, depending on your configuration immediately after + resetting the board or after it has run into an exception. The + easiest way to do it is to use the provided script: ``make gdb``. + +To run manually in Linux: + +.. code-block:: bash + + $ESP_HOME/xtensa-lx106-elf/bin/xtensa-lx106-elf-gdb -x $SMING_HOME/gdb/gdbcmds -b 115200 -ex "target remote /dev/ttyUSB0" + +Windows command line: + +.. code-block:: batch + + %ESP_HOME%\xtensa-lx106-elf\bin\xtensa-lx106-elf-gdb -x %SMING_HOME%\gdb\gdbcmds -b 115200 -ex "target remote COM4" + +In both cases the appropriate baud rate and COM port should be +substituted. + +Useful GDB commands +------------------- + +``c`` Continue execution + +``q`` Quit and detach + +``where`` Display current stopped location + +``bt`` Show stack backtrace + +``disass`` Disassemble, ``disass/m`` to mix with source code + +``print expr`` Display a variable or other value + +``print func()`` Call a function, display result, or ``call func()`` to +discard result + +``tui enable`` Provides a windowed interface within the console (only +seems to work in Linux) + +``x/32xw $sp`` Display contents of stack + +``info reg`` Display register values + +``info break`` Display details of currently set breakpoints + +``delete`` Delete all breakpoints + +``br`` Set a breakpoint at the given address or function name + +``hbr`` Set a hardware breakpoint + +``watch`` Set a hardware watchpoint to detect when the value of a +variable changes + +These commands require ``GDBSTUB_ENABLE_HOSTIO`` to be enabled: + +``remote get targetfile hostfile`` Read a file from SPIFFS (on the +target) + +``remote put hostfile targetfile`` Write a file to SPIFFS + +``remote delete targetfile`` Delete a file from SPIFFS + +Eclipse +------- + +Windows: + +- Ensure ``Use external console for inferior`` is checked. +- In connection settings, specify COM port like with leading /, + e.g. \ ``/COM4`` + +Problems connecting? + +- Switch to the debug perspective before connecting +- Ensure serial baud rate matches your application +- Remove or disable all breakpoints before attaching. Eclipse will + attempt to set these on connection, and if any are invalid it will + hang and timeout. +- Check connectivity using command-line GDB + +GDB System Calls +---------------- + +Applications may interact with GDB directly using system calls, for +example reading input from the GDB command prompt. See the +:sample:`LiveDebug` sample for a demonstration. + +Note that system calls are disabled in the default configuration, so set +:c:macro:`GDBSTUB_ENABLE_SYSCALL` =1 to use this feature with your +application. + +Known Issues and Limitations +---------------------------- + +- Unable to set requested break/watch points + - Cause: Due to hardware limitations, only one hardware + breakpount and one hardware watchpoint are available + - Solution: None (hardware limitation) + +- System crashes if debugger is paused for too long + - Cause: The WiFi hardware is designed to be serviced by + software periodically. It has some buffers so it will behave OK + when some data comes in while the processor is busy, but these + buffers are not infinite. If the WiFi hardware receives lots of + data while the debugger has stopped the CPU, it is bound to crash. + This will happen mostly when working with UDP and/or ICMP; + TCP-connections in general will not send much more data when the + other side doesn’t send any ACKs. + - Solution: In such situations avoid pausing the debugger for + extended periods + +- Software breakpoints/watchpoints (‘break’ and ‘watch’) don’t work on flash code + - Cause: GDB handles these by replacing code with a debugging + instruction, therefore the code must be in RAM. + - Solution: Use hardware breakpoint (‘hbreak’) or use + :c:macro:`GDB_IRAM_ATTR` for code which requires testing + +- If hardware breakpoint is set, single-stepping won’t work unless code is in RAM. + - Cause: GDB reverts to software breakpoints if no hardware + breakpoints are available + - Solution: Delete hardware breakpoint before single-stepping + +- Crash occurs when setting breakpoint in HardwareTimer callback routine + - Cause: By default, HardwareTimer uses Non-maskable Interrupts + (NMI) which keep running when the debugger is paused + - Solution: Use the timer in non-maskable mode, or enable + :c:macro:`GDBSTUB_PAUSE_HARDWARE_TIMER` option + +- If gdbstub isn’t initialised then UART2 won’t work, though initialisation will succeed + - Cause: By design, uart callbacks can be registered for UART2 + at any time, before or after initialisation + - Solution: Not really an issue, just something to be aware of + +- Error reported, “packet reply is too long” + - Cause: Mismatch between GDB version and stub code + - Solution: Set :c:macro:`GDBSTUB_GDB_PATCHED` =1 or use an + unpatched version of GDB + +- Whilst GDB is attached, input cannot be passed to application + - Cause: GDB buffers keystrokes and replays them only when the + target is interrupted (e.g. via ctrl+C), rather than passing them + via serial connection. + - Solution: Application may use gdb_syscall interface to + communicate with debugger. See + ``$(SMING_HOME)/system/gdb_syscall.h``, and :sample:`LiveDebug` + sample. + +- No apparent way to have second ‘console’ (windows terminology) separate from GDB interface + - Cause: Unknown + - Solution: Is this possible with remote targets? + +- GDB (in Windows) doesn’t respond at all to Ctrl+C + - Cause: Unknown + - Solution: Press Ctrl+Break to ‘hard kill’ GDB. You'll probably + need to do the next step as well to get it back + +- When GDB is running under windows, appears to hang when target reset or restarted + - Cause: Unknown, may not happen on all devboards but presents + with NodeMCU + - Solution + - quit GDB ``quit`` + - Start terminal ``make terminal`` + - reset board + - quit terminal + - run GDB again ``make gdb`` + +- Debug messages don’t appear in Eclipse + - Cause: Unknown + - Solution: Use command-line GDB, or a better visual debugger + + +Configuration +------------- + +.. doxygenfile:: gdbstub-cfg.h + diff --git a/Sming/Arch/Esp8266/Components/gdbstub/component.mk b/Sming/Arch/Esp8266/Components/gdbstub/component.mk index 714dfe1d20..b060eb4f2a 100644 --- a/Sming/Arch/Esp8266/Components/gdbstub/component.mk +++ b/Sming/Arch/Esp8266/Components/gdbstub/component.mk @@ -1,5 +1,7 @@ COMPONENT_LIBNAME := +COMPONENT_DEPENDS := esp8266 + COMPONENT_APPCODE := appcode COMPONENT_INCDIRS := . $(ESP8266_COMPONENTS)/driver diff --git a/Sming/Arch/Esp8266/Components/gdbstub/gdbstub-cfg.h b/Sming/Arch/Esp8266/Components/gdbstub/gdbstub-cfg.h index 21ed401a4f..949998239e 100644 --- a/Sming/Arch/Esp8266/Components/gdbstub/gdbstub-cfg.h +++ b/Sming/Arch/Esp8266/Components/gdbstub/gdbstub-cfg.h @@ -12,7 +12,7 @@ #pragma once -/* +/** * When enabled, an exception or crash dumps a stack trace to debug output * Default is ON for debug builds, OFF for release builds * @@ -27,7 +27,7 @@ #endif #endif -/* +/** * When enabled, an unexpected reset (i.e. system crash) dumps a stack trace to debug output * Default is ON for debug builds, OFF for release builds * @@ -41,7 +41,7 @@ #endif #endif -/* +/** * When defined, GDB communications are echoed to UART1 for testing GDB stub operation. * * 0: No debug output @@ -53,7 +53,7 @@ #define GDBSTUB_ENABLE_DEBUG 0 #endif -/* +/** * Espressif provide a patched version of GDB which emits only those registered present in the lx106. * Set to 0 if an unpatched version of GDB is used. */ @@ -61,7 +61,7 @@ #define GDBSTUB_GDB_PATCHED 1 #endif -/* +/** * Enable this to make the exception and debugging handlers switch to a private stack. This will use * up 1K of RAM, but may be useful if you're debugging stack or stack pointer corruption problems. It's * normally disabled because not many situations need it. If for some reason the GDB communication @@ -72,21 +72,21 @@ #define GDBSTUB_STACK_SIZE 256 // In dwords #endif -/* +/** * Enable this to cause the program to pause and wait for gdb to be connected when an exception is encountered. */ #ifndef GDBSTUB_BREAK_ON_EXCEPTION #define GDBSTUB_BREAK_ON_EXCEPTION 1 #endif -/* +/** * Enable this to cause the program to pause and wait for gdb to be connected when an unexpected system restart occurs. */ #ifndef GDBSTUB_BREAK_ON_RESTART #define GDBSTUB_BREAK_ON_RESTART 1 #endif -/* +/** * If this is defined, gdbstub will break the program when you press Ctrl-C in gdb. * It does this by monitoring for the 'x03' character in the serial receive routine. Any preceding * characters are passed through to the application via UART2. @@ -105,7 +105,7 @@ #define GDBSTUB_CTRLC_BREAK 2 #endif -/* +/** * The GDB stub has exclusive access to UART0, so applications cannot use it directly and attempts to * open it will fail. * @@ -127,7 +127,7 @@ #define GDBSTUB_ENABLE_UART2 1 #endif -/* +/** * Enable gdb_syscall_* functions for use by application. * If undefined, calls will do nothing and return -1. */ @@ -135,7 +135,7 @@ #define GDBSTUB_ENABLE_SYSCALL 0 #endif -/* +/** * Enable Host I/O capability, where files may be accessed via GDB command prompt using * `remote get`, `remote put` and `remote delete` commands. */ @@ -143,7 +143,7 @@ #define GDBSTUB_ENABLE_HOSTIO 1 #endif -/* +/** * Enable this if you want the GDB stub to wait for you to attach GDB before running. * It does this by breaking in the init routine; use the gdb 'c' command (continue) to start the program. */ @@ -151,7 +151,7 @@ #define GDBSTUB_BREAK_ON_INIT 1 #endif -/* +/** * Some commands are not required by GDB, so if neccessary can be disabled to save memory. */ // Read/write individual registers @@ -163,7 +163,7 @@ #define GDBSTUB_CMDENABLE_X 1 #endif -/* +/** * Specify a timeout (in milliseconds) when stub is reading from serial port. * Set to 0 to wait indefinitely. */ @@ -171,7 +171,7 @@ #define GDBSTUB_UART_READ_TIMEOUT 0 #endif -/* +/** * Wherever possible gdbstub code is placed in flash memory. * This is fine for most cases, but if debugging whilst flash is disabled or busy (eg during SPI operations * or flash write/erase) then you will need to enable this option to move stub code into IRAM. diff --git a/Sming/Arch/Esp8266/Components/gdbstub/readme.md b/Sming/Arch/Esp8266/Components/gdbstub/readme.md deleted file mode 100644 index 9e26efe10f..0000000000 --- a/Sming/Arch/Esp8266/Components/gdbstub/readme.md +++ /dev/null @@ -1,169 +0,0 @@ -GDBSTUB for Sming -================= - -Background ----------- - -This is a rewrite of gdbstub based on the [esp8266 Arduino project](https://github.com/esp8266/Arduino/pull/5559). - -To use the GNU Debugger (GDB) with Sming requires your application to include some code (`gdbstub`) which communicates via the serial port. On the ESP8266 only UART0 may be used for this as UART1 is transmit-only. - -The gdbstub code will only be built if you specify `ENABLE_GDB=1` when compiling your application. At startup, before your init() function is called, it will claim UART0 so your application will be unable to use it directly. Therefore, the default port for `Serial` is changed to `UART2`. - -UART2 is a 'virtual' serial port to enable serial communications to work correctly when GDB-enabled. Read/write calls and serial callbacks are handled via gdbstub. Baud rate changes affect UART0 directly. - -Note that `target` refers to the application being debugged, and `host` the development system running the GDB program. - -Refer to the official [GDB documention](https://sourceware.org/gdb/current/onlinedocs/gdb/index.html) for further details. - - -GDB ---- - -This is the application which runs on your development system and talks to `gdbstub`. - - * Linux: A version of this should be available in $ESP_HOME/xtensa-lx106-elf/bin/xtensa-lx106-elf-gdb - - * Windows: At time of writing, UDK doesn't provide a GDB application. You can find pre-built version of this at [SysProgs](http://gnutoolchains.com/esp8266/). Download and run the executable installer, then copy the `C:\SysGCC\esp8266\opt\xtensa-lx106-elf\bin\xtensa-lx106-elf-gdb.exe` to a suitable location. - - * Mac: ? - -Usage ------ - - * Configure gdbstub by editing `gdbstub-cfg.h` as required. You can also configure the options by setting `USER_CFLAGS` in your project's `Makefile-user.mk` file. e.g `USER_CFLAGS=-DGDBSTUB_BREAK_ON_INIT=0`. - * Optional: Add `gdb_do_break()` statements to your application. - * Run `make clean`, then `make ENABLE_GDB=1 flash` to build and flash the application with debugging enabled - * Run gdb, depending on your configuration immediately after resetting the board or after it has run into -an exception. The easiest way to do it is to use the provided script: `make gdb`. - -To run manually in Linux: -`$ESP_HOME/xtensa-lx106-elf/bin/xtensa-lx106-elf-gdb -x $SMING_HOME/gdb/gdbcmds -b 115200 -ex "target remote /dev/ttyUSB0"` - -Windows command line: -`%ESP_HOME%\xtensa-lx106-elf\bin\xtensa-lx106-elf-gdb -x %SMING_HOME%\gdb\gdbcmds -b 115200 -ex "target remote COM4"` - -In both cases the appropriate baud rate and COM port should be substituted. - -Useful GDB commands -------------------- - -`c` Continue execution - -`q` Quit and detach - -`where` Display current stopped location - -`bt` Show stack backtrace - -`disass` Disassemble, `disass/m` to mix with source code - -`print expr` Display a variable or other value - -`print func()` Call a function, display result, or `call func()` to discard result - -`tui enable` Provides a windowed interface within the console (only seems to work in Linux) - -`x/32xw $sp` Display contents of stack - -`info reg` Display register values - -`info break` Display details of currently set breakpoints - -`delete` Delete all breakpoints - -`br` Set a breakpoint at the given address or function name - -`hbr` Set a hardware breakpoint - -`watch` Set a hardware watchpoint to detect when the value of a variable changes - -These commands require `GDBSTUB_ENABLE_HOSTIO` to be enabled: - -`remote get targetfile hostfile` Read a file from SPIFFS (on the target) - -`remote put hostfile targetfile` Write a file to SPIFFS - -`remote delete targetfile` Delete a file from SPIFFS - - -Eclipse -------- - -Windows: - - * Ensure `Use external console for inferior` is checked. - * In connection settings, specify COM port like with leading /, e.g. `/COM4` - -Problems connecting? - - * Switch to the debug perspective before connecting - * Ensure serial baud rate matches your application - * Remove or disable all breakpoints before attaching. Eclipse will attempt to set these on connection, and if any are invalid it will hang and timeout. - * Check connectivity using command-line GDB - - -GDB System Calls ----------------- - -Applications may interact with GDB directly using system calls, for example reading input from the GDB command prompt. -See the `LiveDebug` sample for a demonstration. - -Note that system calls are disabled in the default configuration, so set `GDBSTUB_ENABLE_SYSCALL=1` to use this feature with your application. - - -Known Issues and Limitations ----------------------------- - -Unable to set requested break/watch points -- Cause: Due to hardware limitations, only one hardware breakpount and one hardware watchpoint are available -- Solution: None (hardware limitation) - -System crashes if debugger is paused for too long -- Cause: The WiFi hardware is designed to be serviced by software periodically. It has some buffers so it will behave OK when some data comes in while the processor is busy, but these buffers are not infinite. If the WiFi hardware receives lots of data while the debugger has stopped the CPU, it is bound to crash. This will happen mostly when working with UDP and/or ICMP; TCP-connections in general will not send much more data when the other side doesn't send any ACKs. -- Solution: In such situations avoid pausing the debugger for extended periods - -Software breakpoints/watchpoints ('break' and 'watch') don't work on flash code -- Cause: GDB handles these by replacing code with a debugging instruction, therefore the code must be in RAM. -- Solution: Use hardware breakpoint ('hbreak') or use GDB_IRAM_ATTR for code which requires testing - -If hardware breakpoint is set, single-stepping won't work unless code is in RAM. -- Cause: GDB reverts to software breakpoints if no hardware breakpoints are available -- Solution: Delete hardware breakpoint before single-stepping - -Crash occurs when setting breakpoint in HardwareTimer callback routine -- Cause: By default, HardwareTimer uses Non-maskable Interrupts (NMI) which keep running when the debugger is paused -- Solution: Use the timer in non-maskable mode, or enable GDBSTUB_PAUSE_HARDWARE_TIMER option - -If gdbstub isn't initialised then UART2 won't work, though initialisation will succeed -- Cause: By design, uart callbacks can be registered for UART2 at any time, before or after initialisation -- Solution: Not really an issue, just something to be aware of - -Error reported, "packet reply is too long" -- Cause: Mismatch between GDB version and stub code -- Solution: Set `GDBSTUB_GDB_PATCHED=1` or use an unpatched version of GDB - -Whilst GDB is attached, input cannot be passed to application -- Cause: GDB buffers keystrokes and replays them only when the target is interrupted (e.g. via ctrl+C), rather than passing them via serial connection. -- Solution: Application may use gdb_syscall interface to communicate with debugger. See `$(SMING_HOME)/system/gdb_syscall.h`, and LiveDebug sample. - -No apparent way to have second 'console' (windows terminology) separate from GDB interface -- Cause: Unknown -- Solution: Is this possible with remote targets? - -When GDB is running under windows, appears to hang when target reset or restarted -- Cause: Unknown, may not happen on all devboards but presents with NodeMCU -- Solution - - quit GDB `quit` - - Start terminal `make terminal` - - reset board - - quit terminal - - run GDB again `make gdb` - -GDB (in Windows) doesn't respond at all to Ctrl+C -- Cause: Unknown -- Solution: Press Ctrl+Break to 'hard kill' GDB - -Debug messages don't appear in Eclipse -- Cause: Unknown -- Solution: Use command-line GDB, or a better visual debugger diff --git a/Sming/Arch/Esp8266/Components/lwip2/README.rst b/Sming/Arch/Esp8266/Components/lwip2/README.rst new file mode 100644 index 0000000000..9432be959c --- /dev/null +++ b/Sming/Arch/Esp8266/Components/lwip2/README.rst @@ -0,0 +1,4 @@ +Esp8266 LWIP Version 2 +====================== + +This Component implements the current Version 2 LWIP stack. Note that at present espconn\_* functions are not supported. diff --git a/Sming/Arch/Esp8266/Components/lwip2/component.mk b/Sming/Arch/Esp8266/Components/lwip2/component.mk index 3601ddce63..71746ac75d 100644 --- a/Sming/Arch/Esp8266/Components/lwip2/component.mk +++ b/Sming/Arch/Esp8266/Components/lwip2/component.mk @@ -1,6 +1,8 @@ # For now, build as a regular library using existing makefile (variants not supported) COMPONENT_LIBNAME := +COMPONENT_DEPENDS := esp8266 + ifeq ($(SMING_RELEASE),1) COMPONENT_CFLAGS := \ -DLWIP_NOASSERT \ diff --git a/Sming/Arch/Esp8266/Components/pwm_open/README.rst b/Sming/Arch/Esp8266/Components/pwm_open/README.rst new file mode 100644 index 0000000000..2803dccc73 --- /dev/null +++ b/Sming/Arch/Esp8266/Components/pwm_open/README.rst @@ -0,0 +1,4 @@ +Esp8266 Open PWM +================ + +Implements a drop-in replacement for the PWM support provided in the Espressif SDK. diff --git a/Sming/Arch/Esp8266/Components/pwm_open/component.mk b/Sming/Arch/Esp8266/Components/pwm_open/component.mk index 114287be86..0641aa25c7 100644 --- a/Sming/Arch/Esp8266/Components/pwm_open/component.mk +++ b/Sming/Arch/Esp8266/Components/pwm_open/component.mk @@ -1,4 +1,6 @@ +COMPONENT_DEPENDS := esp8266 + COMPONENT_SUBMODULES := new-pwm COMPONENT_SRCDIRS := new-pwm COMPONENT_CFLAGS := -DSDK_PWM_PERIOD_COMPAT_MODE=1 diff --git a/Sming/Arch/Esp8266/Components/rboot/esptool2.patch b/Sming/Arch/Esp8266/Components/rboot/.patches/esptool2.patch similarity index 100% rename from Sming/Arch/Esp8266/Components/rboot/esptool2.patch rename to Sming/Arch/Esp8266/Components/rboot/.patches/esptool2.patch diff --git a/Sming/Arch/Esp8266/Components/rboot/.patches/esptool2/README.rst b/Sming/Arch/Esp8266/Components/rboot/.patches/esptool2/README.rst new file mode 100644 index 0000000000..0f5aa4bb77 --- /dev/null +++ b/Sming/Arch/Esp8266/Components/rboot/.patches/esptool2/README.rst @@ -0,0 +1,21 @@ +Esptool2 +======== + +richardaburton@gmail.com +http://richard.burtons.org/ + +Esptool2 is a tool for creating rom images for the ESP8266. It is an alternative +to using the SDK supplied shell script/Makefile/python script combo, which is a +mess. It was inspired by the windows esptool v0.0.2 by mamalala and found on +www.esp8266.com but made somewhat simpler in code and usage. It also adds +support for boot loader v1.2+ rom types, which was the main reason I wrote it. + +It was written for my own use and the name was simply to distinguish it for the +other version on my system. The 2 is not intended to imply it is better than the +original. The original has since been updated to v0.0.3 which can write to the +flash, but I currently have no intention to add that to esptool2, it is purely a +rom creating utility. It has become an integral part of my build process now and +has added functionality needed for building the rBoot boot loader. Since I have +released rBoot I needed to release this as well. + +Run tool for full usage instructions, or look at the code. diff --git a/Sming/Arch/Esp8266/Components/rboot/rboot.patch b/Sming/Arch/Esp8266/Components/rboot/.patches/rboot.patch similarity index 100% rename from Sming/Arch/Esp8266/Components/rboot/rboot.patch rename to Sming/Arch/Esp8266/Components/rboot/.patches/rboot.patch diff --git a/Sming/Arch/Esp8266/Components/rboot/.patches/rboot/README.rst b/Sming/Arch/Esp8266/Components/rboot/.patches/rboot/README.rst new file mode 100644 index 0000000000..56f2f90737 --- /dev/null +++ b/Sming/Arch/Esp8266/Components/rboot/.patches/rboot/README.rst @@ -0,0 +1,341 @@ +================================================== +rBoot - An open source boot loader for the ESP8266 +================================================== + +by Richard A Burton, richardaburton@gmail.com +http://richard.burtons.org/ + +rBoot is designed to be a flexible open source boot loader, a +replacement for the binary blob supplied with the SDK. It has the +following advantages over the Espressif loader: + +- Open source (written in C). +- Supports up to 256 roms. +- Roms can be variable size. +- Able to test multiple roms to find a valid backup (without + resetting). +- Flash layout can be changed on the fly (with care and appropriately + linked rom images). +- GPIO support for rom selection. +- Wastes no stack space (SDK boot loader uses 144 bytes). +- Documented config structure to allow easy editing from user code. +- Can validate .irom0.text section with checksum. +- Temporary next-boot rom selection. + +Limitations +=========== + +The ESP8266 can only map 8Mbits (1MB) of flash to memory, but which +8Mbits to map is selectable. This allows individual roms to be up to 1MB +in size, so long as they do not straddle an 8Mbit boundary on the flash. +This means you could have four 1MB roms or 8 512KB roms on a 32Mbit +flash (such as on the ESP-12), or a combination. Note, however, that you +could not have, for example, a 512KB rom followed immediately by a 1MB +rom because the 2nd rom would then straddle an 8MBit boundary. By +default support for using more than the first 8Mbit of the flash is +disabled, because it requires several steps to get it working. See below +for instructions. + +Building +======== + +A Makefile is included, which should work with the gcc xtensa cross +compiler. There are two source files, the first is compiled and included +as data in the second. When run this code is copied to memory and +executed (there is a good reason for this, see my blog for an +explanation). The make file will handle this for you, but you’ll need my +esptool2 (see github). + +To use the Makefile set ``SDK_BASE`` to point to the root of the +Espressif SDK and either set ``XTENSA_BINDIR`` to the gcc xtensa bin +directory or include it in your ``PATH``. These can be set as +environment variables or by editing the Makefile. + +Two small assembler stub functions allow the bootloader to launch the +user code without reserving any space on the stack (while the SDK boot +loader uses 144 bytes). This compiles fine with GCC, but if you use +another compiler and it will not compile/work for you then uncomment the +``#define BOOT_NO_ASM`` in ``rboot.h`` to use a C version of these +functions (this uses 32 bytes). + +Tested with SDK v2.2 and GCC v4.8.5. + +Installation +============ + +Simply write rboot.bin to the first sector of the flash. Remember to set +your flash size correctly with your chosen flash tool (e.g. for +esptool.py use the ``-fs`` option). When run rBoot will create it’s own +config at the start of sector two for a simple two rom system. You can +can then write your two roms to flash addresses ``0x2000`` and (half +chip size + ``0x2000``). E.g. for 8Mbit flash: +``esptool.py write_flash -fs 8m 0x0000 rboot.bin 0x2000 user1.bin 0x82000 user2.bin`` + +Note: your device may need other options specified. E.g. The nodemcu +devkit v1.0 (commonly, but incorrectly, sold as v2) also needs the +``-fm dio`` option. + +For more interesting rom layouts you’ll need to write an rBoot config +sector manually, see next step. + +The two testload bin files can be flashed in place of normal user roms +for testing rBoot. You do not need these for normal use. + +rBoot Config +============ + +:: + + typedef struct { + uint8_t magic; // our magic + uint8_t version; // config struct version + uint8_t mode; // boot loader mode + uint8_t current_rom; // currently selected rom + uint8_t gpio_rom; // rom to use for gpio boot + uint8_t count; // number of roms in use + uint8_t unused[2]; // padding + uint32_t roms[MAX_ROMS]; // flash addresses of the roms + #ifdef BOOT_CONFIG_CHKSUM + uint8_t chksum; // boot config chksum + #endif + } rboot_config; + +Write a config structure as above to address ``0x1000`` on the flash. If +you want more than 4 roms (default) just increase MAX_ROMS when you +compile rBoot. Think about how you intend to layout your flash before +you start! Rom addresses must be sector aligned i.e start on a multiple +of 4096. + +- ``magic`` should have value ``0xe1`` (defined as + ``BOOT_CONFIG_MAGIC``). +- ``version`` is used in case the config structure changes after + deployment. It is defined as ``0x01`` (``BOOT_CONFIG_VERSION``). I + don’t intend to increase this, but you should if you choose to + reflash the bootloader after deployment and the config structure has + changed. +- ``mode`` can be ``0x00`` (``MODE_STANDARD``) or ``0x01`` + (``MODE_GPIO_ROM``). See below for an explanation of + ``MODE_GPIO_ROM``. There is also an optional extra mode flag ``0x04`` + (``MODE_GPIO_ERASES_SDKCONFIG``), see below for details. +- ``current_rom`` is the rom to boot, numbered ``0`` to ``count-1``. +- ``gpio_rom`` is the rom to boot when the GPIO is triggered at boot. +- ``count`` is the number of roms available (may be less than + ``MAX_ROMS``, but not more). +- ``unused[2]`` is padding so the ``uint32_t`` rom addresses are 4 + bytes aligned. +- ``roms`` is the array of flash address for the roms. The default + generated config will contain two entries: ``0x00002000`` and + ``0x00082000``. +- ``chksum`` (if enabled, not by deafult) should be the xor of ``0xef`` + followed by each of the bytes of the config structure up to (but + obviously not including) the chksum byte itself. + +Default config +============== + +A default config sector will be created on boot if one does not exists, +or if an existing config is corrupted, and the default rom will be set +to rom 0. If you want to have a very customised config for which the +default would not be suitable, you can override the implementation in +the ``rboot.h`` header file. See the comments and example code in +``rboot.h`` for more information. + +GPIO boot mode +============== + +If rBoot is compiled with ``BOOT_GPIO_ENABLED`` set in ``rboot.h`` (or +``RBOOT_GPIO_ENABLED`` set in the Makefile), then GPIO boot +functionality will be included in the rBoot binary. The feature can then +be enabled by setting the rboot_config ``mode`` field to +``MODE_GPIO_ROM``. You must also set ``gpio_rom`` in the config to +indicate which rom to boot when the GPIO is activated at boot. + +If the GPIO input pin reads high at boot then rBoot will start the +currently selected normal or temp rom (as appropriate). However if the +GPIO is pulled low then the rom indicated in config option ``gpio_rom`` +is started instead. + +The default GPIO is 16, but this can be overriden in the Makefile +(``RBOOT_GPIO_NUMBER``) or ``rboot.h`` (``BOOT_GPIO_NUM``). If GPIOs +other than 16 are used, the internal pullup resistor is enabled before +the pin is read and disabled immediately afterwards. For pins that +default on reset to configuration other than GPIO input, the pin mode is +changed to input when reading but changed back before rboot continues. + +After a GPIO boot the ``current_rom`` field will be updated in the +config, so the GPIO booted rom should change this again if required. + +GPIO boot skip mode +=================== + +If rBoot is compiled with ``BOOT_GPIO_SKIP_ENABLED`` set in ``rboot.h`` +(or ``RBOOT_GPIO_SKIP_ENABLED`` set in the Makefile), then a GPIO can be +used to skip to the next rom at boot. The feature must then be enabled +by setting the rboot_config ‘mode’ field to ``MODE_GPIO_SKIP``. This +means you do not need to have a dedicated GPIO boot rom. If you have a +rom that is technically good (valid checksum, etc.) but has operational +problems, e.g. wifi doesn’t work or it crashes on boot, rBoot will not +be able to detect that and switch rom automatically. In this scenario +rebooting the device while pulling the GPIO low will force rBoot to skip +this rom and try the next one instead. In a simple two rom setup this +simply toggles booting of the other rom. + +``RBOOT_GPIO_SKIP_ENABLED`` and ``RBOOT_GPIO_ENABLED`` cannot be used at +the same time. ``BOOT_GPIO_NUM`` is used to select the GPIO pin, as with +``RBOOT_GPIO_ENABLED``. + +Erasing SDK configuration on GPIO boot (rom or skip mode) +========================================================= + +If you set the ``MODE_GPIO_ERASES_SDKCONFIG`` flag in the configuration +like this: ``conf.mode = MODE_GPIO_ROM|MODE_GPIO_ERASES_SDKCONFIG``; +then a GPIO boot will also the erase the Espressif SDK persistent +settings store in the final 16KB of flash. This includes removing +calibration constants, saved SSIDs, etc. + +Note that ``MODE_GPIO_ERASES_SDKCONFIG`` is a flag, so it has to be set +as well as ``MODE_GPIO_ROM`` to take effect. + +Linking user code +================= + +Each rom will need to be linked with an appropriate linker file, +specifying where it will reside on the flash. If you are only flashing +one rom to multiple places on the flash it must be linked multiple times +to produce the set of rom images. This is the same as with the SDK +loader. + +Because there are endless possibilities for layout with this loader I +don’t supply sample linker files. Instead I’ll tell you how to make +them. + +For each rom slot on the flash take a copy of the ``eagle.app.v6.ld`` +linker script from the sdk. You then need to modify just one line in it +for each rom: +``irom0_0_seg : org = 0x40240000, len = 0x3C000`` + +Change the org address to be ``0x40200000`` (base memory mapped location +of the flash) + flash address + ``0x10`` (offset of data after the +header). The logical place for your first rom is the third sector, +address ``0x2000``. ``0x40200000 + 0x2000 + 0x10 = 0x40202010`` If you +use the default generated config the loader will expect to find the +second rom at flash address half-chip-size + ``0x2000`` +(e.g. ``0x82000`` on an 8MBit flash) so the ``irom0_0_seg`` should be: +``0x40200000 + 0x82000 + 0x10 = 0x40282010`` Due to the limitation of +mapped flash (max 8MBit) if you use a larger chip and do not have big +flash support enabled the second rom in the default config will still be +placed at ``0x082000``, not truly half-chip-size + ``0x2000``. Ideally +you should also adjust the len to help detect over sized sections at +link time, but more important is the overall size of the rom which you +need to ensure fits in the space you have allocated for it in your flash +layout plan. + +Then simply compile and link as you would normally for OTA updates with +the SDK boot loader, except using the linker scripts you’ve just +prepared rather than the ones supplied with the SDK. Remember when +building roms to create them as ‘new’ type roms (for use with SDK boot +loader v1.2+). Or if using my esptool2 use the ``-boot2`` option. Note: +the test loads included with rBoot are built with ``-boot0`` because +they do not contain a ``.irom0.text`` section (and so the value of +``irom0_0_seg`` in the linker file is irrelevant to them) but ‘normal’ +user apps always do. + +irom checksum +============= + +The SDK boot loader checksum only covers sections loaded into ram (data +and some code). Most of the SDK and user code remains on the flash and +that is not included in the checksum. This means you could attempt to +boot a corrupt rom and, because it looks ok to the boot loader, there +will be no attempt to switch to a backup rom. rBoot improves on this by +allowing the ``.irom0.text`` section to be included in the checksum. To +enable this uncomment ``#define BOOT_IROM_CHKSUM`` in ``rboot.h`` and +build your roms with esptool2 using the ``-iromchksum`` option. + +Big flash support +================= + +This only needs to be enabled if you wish to be able to memory map more +than the first 8MBit of the flash. Note you can still only map 8Mbit at +a time. Use this if you want to have multiple 1MB roms, or more smaller +roms than will fit in 8Mbits. If you have a large flash but only need, +for example, two 512KB roms you do not need to enable this mode. + +Support in rBoot is enabled by uncommenting the +``#define BOOT_BIG_FLASH`` in ``rboot.h``. + +Thinking about your linker files is either simpler or more complicated, +depending on your usage of the flash. If you intend to use multiple 1MB +roms you will only need one linker file and you only need to link once +for OTA updates. Although when you perform an OTA update the rom will be +written to a different position on the flash, each 8Mbit of flash is +mapped (separately) to ``0x40200000``. So when any given rom is run the +code will appear at the same place in memory regardless of where it is +on the flash. Your base address for the linker would be ``0x40202010``. +(Actually all but the first rom could base at ``0x40200010`` (because +they don’t need to leave space for rBoot and config) but then you’re +just making it more complicated again!) + +If you wanted eight 512KB roms you would need two linker files - one for +the first half of any given 8Mbits of flash and another for the second +half. Just remember you are really laying out within a single 8MBit +area, which can then be replicated multiple times on the flash. + +Now the clever bit - rBoot needs to hijack the memory mapping code to +select which 8Mbits gets mapped. There is no API for this, but we can +override the SDK function. First we need to slightly modify the SDK +library ``libmain.a``, like so: + +:: + + xtensa-lx106-elf-objcopy -W Cache_Read_Enable_New libmain.a libmain2.a + +This produces a version of libmain with a ‘weakened’ +``Cache_Read_Enable_New`` function, which we can then override with our +own. Modify your Makefile to link against the library ``main2`` instead +of ``main``. + +Next add ``rboot-bigflash.c`` (from the ``appcode`` directory) & +``rboot.h`` to your project - this adds the replacement +``Cache_Read_Enable_New`` to your code. + +Getting gcc to apply the override correctly can be slightly tricky (I’m +not sure why, it shouldn’t be). One option is to add +``-u Cache_Read_Enable_New`` to your ``LD_FLAGS`` and change the order +of objects on the LD command so your ``objects/.a`` file is before the +libraries. Another way that seems easier was to +``#include rboot-bigflash.c`` into the main .c file, rather than +compiling it to a separate object file. I can’t make any sense of that, +but I suggest you uncomment the message in the ``Cache_Read_Enable_New`` +function when you first build with it, to make sure you are getting your +version into the rom. + +Now when rBoot starts your rom, the SDK code linked in it that normally +performs the memory mapping will delegate part of that task to rBoot +code (linked in your rom, not in rBoot itself) to choose which part of +the flash to map. + +Temporary boot option and rBoot<–>app communication +=================================================== + +To enable communication between rBoot and your app you should enable the +``BOOT_RTC_ENABLED`` option in ``rboot.h``. rBoot will then use the RTC +data area to pass a structure with boot information which can be read by +the app. This will allow the app to determine the boot mode (normal, +temporary or GPIO) and the booted rom (even if it is a tempoary boot). +Your app can also update this structure to communicate with rBoot when +the device is next rebooted, e.g. to instruct it to temporarily boot a +different rom to the one saved in the config. See the api documentation +and/or the rBoot sample project for more details. Note: the message +“don’t use rtc mem data”, commonly seen on startup, comes from the sdk +and is not related to this rBoot feature. + +Integration into other frameworks +================================= + +If you wish to integrate rBoot into a development framework (e.g. Sming) +you can set the define ``RBOOT_INTEGRATION`` and at compile time the +file ``rboot-integration.h`` will be included into the source. This +should allow you to set some platform specific options without having to +modify the source of rBoot which makes it easier to integrate and +maintain. diff --git a/Sming/Arch/Esp8266/Components/rboot/README.rst b/Sming/Arch/Esp8266/Components/rboot/README.rst new file mode 100644 index 0000000000..c6d74af50f --- /dev/null +++ b/Sming/Arch/Esp8266/Components/rboot/README.rst @@ -0,0 +1,9 @@ +rBoot +===== + +Sming uses rBoot exclusively because of its flexibility, reliability and +ease of use. + +This Component also includes esptool2 which rBoot uses to manipulate ROM +images. Use ``$(ESPTOOL2)`` if you want to use it within your own +projects. diff --git a/Sming/Arch/Esp8266/Components/rboot/component.mk b/Sming/Arch/Esp8266/Components/rboot/component.mk index 0f851f6f97..89ac785641 100644 --- a/Sming/Arch/Esp8266/Components/rboot/component.mk +++ b/Sming/Arch/Esp8266/Components/rboot/component.mk @@ -1,5 +1,7 @@ COMPONENT_LIBNAME := +COMPONENT_DEPENDS := esp8266 + COMPONENT_SUBMODULES := rboot esptool2 COMPONENT_INCDIRS := rboot appcode rboot/appcode diff --git a/Sming/Arch/Esp8266/Components/sming-arch/README.rst b/Sming/Arch/Esp8266/Components/sming-arch/README.rst new file mode 100644 index 0000000000..c3cef9cc50 --- /dev/null +++ b/Sming/Arch/Esp8266/Components/sming-arch/README.rst @@ -0,0 +1,84 @@ +Sming (Esp8266) +=============== + +This Component builds a library containing architecture-specific code, and defines dependencies for Sming to build for the Esp8266. + +SDK 3.0+ +-------- + +Default: OFF. In order to use SDK 3.0.0 or newer please follow the instructions here :component-esp8266:`esp8266`. + +Custom LWIP +----------- + +`LWIP `__ (LightWeight IP) is a small independent implementation +of the TCP/IP protocol suite used widely in embedded systems. Sming supports several versions of this, +controlled by the :envvar:`ENABLE_CUSTOM_LWIP` setting. + +.. envvar:: ENABLE_CUSTOM_LWIP + + 0 + Use binary :component-esp8266:`esp-lwip` stack. + 1 (default) + Use custom compiled :component-esp8266:`esp-open-lwip` stack. + Compared with the Espressif stack, this uses less RAM but + consumes FLASH (program) memory. All espconn\_* functions are turned off by default, so if you require these add + the :envvar:`ENABLE_ESPCONN` =1 directive. The :sample:`Basic_SmartConfig` example sets this in its ``component.mk`` + file. + 2 + Use :component-esp8266:`lwip2` stack. This does not have support for espconn\_* functions. + +.. envvar:: ENABLE_LWIP_DEBUG + + By default, some debug information will be printed for critical errors and situations. + Set this to 1 to enable printing of all debug information. + + +SSL support +----------- + +.. envvar:: ENABLE_SSL + + SSL requires lots of RAM and some intensive processing, so to conserve resources it is disabled by default. + If you want to enable it then take a look at the :sample:`Basic_Ssl` sample. + + Set to 1 to enable SSL support using the :component-esp8266:`axtls-8266` Component. + +Custom heap allocation +---------------------- + +.. envvar:: ENABLE_CUSTOM_HEAP + + If your application is experiencing heap fragmentation then you can try the alternative heap. + + undefined (default) + OFF, use standard heap + + 1 + Use :component-esp8266:`custom_heap` + + +Custom PWM +---------- + +.. envvar:: ENABLE_CUSTOM_PWM + + undefined + use the Espressif PWM driver + 1 (default) + use :component-esp8266:`pwm_open`. + + +Interactive debugging on the device +----------------------------------- + +.. envvar:: ENABLE_GDB + + In order to be able to debug live directly on the ESP8266 microcontroller you + should re-compile your application with ``ENABLE_GDB=1`` directive. + + undefined (default) + Compile normally + 1 + Compile with debugging support provided by :component-esp8266:`gdbstub`. + See also the :sample:`LiveDebug` sample. diff --git a/Sming/Arch/Esp8266/Components/spi_flash/README.rst b/Sming/Arch/Esp8266/Components/spi_flash/README.rst new file mode 100644 index 0000000000..b7ea8da337 --- /dev/null +++ b/Sming/Arch/Esp8266/Components/spi_flash/README.rst @@ -0,0 +1,6 @@ +Esp8266 SPI Flash Support +========================= + +Provides functions for access to flash memory. + +.. doxygenfile:: esp_spi_flash.h diff --git a/Sming/Arch/Esp8266/Components/spi_flash/component.mk b/Sming/Arch/Esp8266/Components/spi_flash/component.mk new file mode 100644 index 0000000000..5fee1d9bc1 --- /dev/null +++ b/Sming/Arch/Esp8266/Components/spi_flash/component.mk @@ -0,0 +1 @@ +COMPONENT_DEPENDS := esp8266 diff --git a/Sming/Arch/Esp8266/Components/spi_flash/include/esp_spi_flash.h b/Sming/Arch/Esp8266/Components/spi_flash/include/esp_spi_flash.h index ec354ca9d8..cba56c919d 100644 --- a/Sming/Arch/Esp8266/Components/spi_flash/include/esp_spi_flash.h +++ b/Sming/Arch/Esp8266/Components/spi_flash/include/esp_spi_flash.h @@ -17,12 +17,13 @@ extern "C" { #include -// Flash memory access must be aligned and in multiples of 4-byte words +/// Flash memory access must be aligned and in multiples of 4-byte words #define INTERNAL_FLASH_WRITE_UNIT_SIZE 4 #define INTERNAL_FLASH_READ_UNIT_SIZE 4 #define FLASH_TOTAL_SEC_COUNT (flashmem_get_size_sectors()) +/// Number of flash sectors reserved for system parameters at start #define SYS_PARAM_SEC_COUNT 4 #define FLASH_WORK_SEC_COUNT (FLASH_TOTAL_SEC_COUNT - SYS_PARAM_SEC_COUNT) @@ -61,10 +62,10 @@ typedef struct } size : 4; } STORE_TYPEDEF_ATTR SPIFlashInfo; -/** @brief obtain the flash memory address for a memory pointer +/** @brief Obtain the flash memory address for a memory pointer * @param memptr - * @retval uint32_t offset from start of flash memory - * @note if memptr is not in valid flash memory it will return an offset which exceeds + * @retval uint32_t Offset from start of flash memory + * @note If memptr is not in valid flash memory it will return an offset which exceeds * the internal flash memory size. This is caught by constructors using getMaxSize() * to provide a zero-length extent. */ @@ -73,20 +74,20 @@ static inline uint32_t flashmem_get_address(const void* memptr) return (uint32_t)memptr - INTERNAL_FLASH_START_ADDRESS; } -/** @brief write a block of data to flash - * @param from buffer to obtain data from - * @param toaddr flash location to start writing - * @param size number of bytes to write - * @retval uint32_t number of bytes written - * @note none of the parameters need to be aligned +/** @brief Write a block of data to flash + * @param from Buffer to obtain data from + * @param toaddr Flash location to start writing + * @param size Number of bytes to write + * @retval uint32_t Number of bytes written + * @note None of the parameters need to be aligned */ uint32_t flashmem_write(const void* from, uint32_t toaddr, uint32_t size); -/** @brief read a block of data from flash - * @param to buffer to store data - * @param fromaddr flash location to start reading - * @param size number of bytes to read - * @retval uint32_t number of bytes written +/** @brief Read a block of data from flash + * @param to Buffer to store data + * @param fromaddr Flash location to start reading + * @param size Number of bytes to read + * @retval uint32_t Number of bytes written * @note none of the parameters need to be aligned */ uint32_t flashmem_read(void* to, uint32_t fromaddr, uint32_t size); @@ -97,61 +98,62 @@ uint32_t flashmem_read(void* to, uint32_t fromaddr, uint32_t size); */ bool flashmem_erase_sector(uint32_t sector_id); -/** @brief get flash memory information block - * @retval SPIFlashInfo information block +/** @brief Get flash memory information block + * @retval SPIFlashInfo Information block */ SPIFlashInfo flashmem_get_info(); /** @brief Returns a number indicating the size of flash memory chip - * @retval see SpiFlashInfo.size field for possible values + * @retval uint8_t See SpiFlashInfo.size field for possible values */ uint8_t flashmem_get_size_type(); /** @brief get the total flash memory size - * @retval uint32_t size in bytes + * @retval uint32_t Size in bytes */ uint32_t flashmem_get_size_bytes(); -/** @brief get the total number of flash sectors - * @retval uint16_t sector count +/** @brief Get the total number of flash sectors + * @retval uint16_t Sector count */ uint16_t flashmem_get_size_sectors(); /** @brief Helper function: find the flash sector in which an address resides * @param address - * @param pstart OUT/OPTIONAL: start of sector containing the given address - * @param pend OUT/OPTIONAL: last address in sector - * @retval uint32_t sector number for the given address - * @note optional parameters may be null + * @param pstart OUT/OPTIONAL: Start of sector containing the given address + * @param pend OUT/OPTIONAL: Last address in sector + * @retval uint32_t Sector number for the given address + * @note Optional parameters may be null */ uint32_t flashmem_find_sector(uint32_t address, uint32_t* pstart, uint32_t* pend); /** @brief Get sector number containing the given address + * @param addr * @retval uint32_t sector number */ uint32_t flashmem_get_sector_of_address(uint32_t addr); /** @brief write to flash memory - * @param to buffer to read data from - MUST be word-aligned - * @param toaddr flash address (offset) to write to - MUST be word-aligned - * @param size number of bytes to write - MUST be word-aligned - * @retval number of bytes actually written + * @param from Buffer to read data from - MUST be word-aligned + * @param toaddr Flash address (offset) to write to - MUST be word-aligned + * @param size Number of bytes to write - MUST be word-aligned + * @retval uint32_t Number of bytes actually written * @note All parameters MUST be aligned to 4-byte word boundaries, **including** the RAM pointer */ uint32_t flashmem_write_internal(const void* from, uint32_t toaddr, uint32_t size); -/** @brief read from flash memory - * @param to buffer to store data - MUST be word-aligned - * @param fromaddr flash address (offset) to read from - MUST be word-aligned - * @param size number of bytes to read - MUST be word-aligned - * @retval number of bytes actually read +/** @brief Read from flash memory + * @param to Buffer to store data - MUST be word-aligned + * @param fromaddr Flash address (offset) to read from - MUST be word-aligned + * @param size Number of bytes to read - MUST be word-aligned + * @retval uint32_t Number of bytes actually read * @note All parameters MUST be aligned to 4-byte word boundaries, **including** the RAM pointer */ uint32_t flashmem_read_internal(void* to, uint32_t fromaddr, uint32_t size); /* * @brief Returns the address of the first free block on flash - * @retval uint32_t the actual address on flash + * @retval uint32_t The actual address on flash */ uint32_t flashmem_get_first_free_block_address(); diff --git a/Sming/Arch/Esp8266/README.rst b/Sming/Arch/Esp8266/README.rst new file mode 100644 index 0000000000..30efe5ff33 --- /dev/null +++ b/Sming/Arch/Esp8266/README.rst @@ -0,0 +1,15 @@ +Sming Esp8266 Architecture +========================== + +Support building Sming for the Esp8266 architecture. + +Components +---------- + +.. toctree:: + :glob: + :maxdepth: 1 + :titlesonly: + + Components/sming-arch/index + Components/*/index diff --git a/Sming/Arch/Host/Components/driver/README.rst b/Sming/Arch/Host/Components/driver/README.rst new file mode 100644 index 0000000000..b64b32eb8a --- /dev/null +++ b/Sming/Arch/Host/Components/driver/README.rst @@ -0,0 +1,14 @@ +Host Drivers +============ + +Provides low-level peripheral support classes. + +* ADC: Analogue functions +* GPIO: General-purpose I/O +* PWM: Common header for PWM support + +UART +---- + +Implements a UART driver to connect via TCP sockets, allowing terminal emulation using telnet. +Depends on :component-host:`hostlib`. diff --git a/Sming/Arch/Host/Components/esp_hal/README.rst b/Sming/Arch/Host/Components/esp_hal/README.rst new file mode 100644 index 0000000000..119fab3c62 --- /dev/null +++ b/Sming/Arch/Host/Components/esp_hal/README.rst @@ -0,0 +1,8 @@ +Host ESP HAL +============ + +Provides implementations for various low-level functions similar to the Esp8266. + +* Task queues +* Timer queues +* System functions diff --git a/Sming/Arch/Host/Components/esp_hal/component.mk b/Sming/Arch/Host/Components/esp_hal/component.mk index 8be549e01b..dcbcda3651 100644 --- a/Sming/Arch/Host/Components/esp_hal/component.mk +++ b/Sming/Arch/Host/Components/esp_hal/component.mk @@ -1 +1,3 @@ COMPONENT_INCDIRS += $(ESP8266_COMPONENTS)/esp8266/include + +COMPONENT_DEPENDS := hostlib diff --git a/Sming/Arch/Host/Components/esp_wifi/README.rst b/Sming/Arch/Host/Components/esp_wifi/README.rst new file mode 100644 index 0000000000..18270f816d --- /dev/null +++ b/Sming/Arch/Host/Components/esp_wifi/README.rst @@ -0,0 +1,4 @@ +Host WiFi +========= + +Provides WiFi / network functions. The actual implementations are provided in :component-host:`lwip` diff --git a/Sming/Arch/Host/Components/esp_wifi/component.mk b/Sming/Arch/Host/Components/esp_wifi/component.mk index 873efad97f..88d5fb36a6 100644 --- a/Sming/Arch/Host/Components/esp_wifi/component.mk +++ b/Sming/Arch/Host/Components/esp_wifi/component.mk @@ -1,3 +1,5 @@ +COMPONENT_DEPENDS := lwip + # Options to add for configuring host network behaviour CACHE_VARS += HOST_NETWORK_OPTIONS HOST_NETWORK_OPTIONS ?= diff --git a/Sming/Arch/Host/Components/fatfs/README.rst b/Sming/Arch/Host/Components/fatfs/README.rst new file mode 100644 index 0000000000..e53896fe5f --- /dev/null +++ b/Sming/Arch/Host/Components/fatfs/README.rst @@ -0,0 +1,4 @@ +fatfs +===== + +This Component is required to allow some samples to compile for the Host, however it doesn't provide any functionality at present. diff --git a/Sming/Arch/Host/Components/gdbstub/README.rst b/Sming/Arch/Host/Components/gdbstub/README.rst new file mode 100644 index 0000000000..5728592b2d --- /dev/null +++ b/Sming/Arch/Host/Components/gdbstub/README.rst @@ -0,0 +1,5 @@ +GDB Stub for Host +================= + +This defines the command line to use when ``make gdb`` is run. No additional code is required to debug for the Host. + diff --git a/Sming/Arch/Host/Components/heap/README.rst b/Sming/Arch/Host/Components/heap/README.rst new file mode 100644 index 0000000000..58bd7d0cf7 --- /dev/null +++ b/Sming/Arch/Host/Components/heap/README.rst @@ -0,0 +1,5 @@ +Heap +==== + +This Component implements heap-related housekeeping functions. Heap usage is tracked using :component:`malloc_count`. +This also provides some validation (using *sentinels* to detect if memory blocks are overwritten). diff --git a/Sming/Arch/Host/Components/hostlib/README.rst b/Sming/Arch/Host/Components/hostlib/README.rst new file mode 100644 index 0000000000..4d3eb224f5 --- /dev/null +++ b/Sming/Arch/Host/Components/hostlib/README.rst @@ -0,0 +1,17 @@ +Host Library +============ + +This Components provides the core funcionality for the Host Emulator: + +sockets + Classes to provide simple Berkeley socket support for both Linux and Windows + +options + Command line argument parsing + +startup + Initialises :component-host:`spi_flash`, Uart server (in :component-host:`driver`) and :component-host:`lwip` + networking, then enters the main task loop. This loop services LWIP plus the task and timer queues + (implemented in :component-host:`esp_hal`). + The ``Ctrl+C`` keypress is trapped to provide an orderly exit. If the system has become stuck in a loop or is otherwise + unresponsive, subsquent Ctrl+C presses will force a process termination. diff --git a/Sming/Arch/Host/Components/hostlib/component.mk b/Sming/Arch/Host/Components/hostlib/component.mk index d47686c5b0..8b54d3084c 100644 --- a/Sming/Arch/Host/Components/hostlib/component.mk +++ b/Sming/Arch/Host/Components/hostlib/component.mk @@ -3,3 +3,5 @@ EXTRA_LIBS := pthread ifeq ($(UNAME),Windows) EXTRA_LIBS += wsock32 endif + +COMPONENT_DEPENDS := esp_wifi lwip driver spi_flash diff --git a/Sming/Arch/Host/Components/hostlib/startup.cpp b/Sming/Arch/Host/Components/hostlib/startup.cpp index cef78f22bc..7d00d5551d 100644 --- a/Sming/Arch/Host/Components/hostlib/startup.cpp +++ b/Sming/Arch/Host/Components/hostlib/startup.cpp @@ -28,7 +28,7 @@ #include #include #include -#include "host_lwip.h" +#include #include #include diff --git a/Sming/Arch/Host/Components/libc/README.rst b/Sming/Arch/Host/Components/libc/README.rst new file mode 100644 index 0000000000..57bd3a21eb --- /dev/null +++ b/Sming/Arch/Host/Components/libc/README.rst @@ -0,0 +1,4 @@ +libc +==== + +Contains implementations of any non-standard C library functions. diff --git a/Sming/Arch/Host/Components/lwip/lwip.patch b/Sming/Arch/Host/Components/lwip/.patches/lwip.patch similarity index 100% rename from Sming/Arch/Host/Components/lwip/lwip.patch rename to Sming/Arch/Host/Components/lwip/.patches/lwip.patch diff --git a/Sming/Arch/Host/Components/lwip/.patches/lwip/README.rst b/Sming/Arch/Host/Components/lwip/.patches/lwip/README.rst new file mode 100644 index 0000000000..1f46957e2b --- /dev/null +++ b/Sming/Arch/Host/Components/lwip/.patches/lwip/README.rst @@ -0,0 +1,112 @@ +INTRODUCTION +============ + +lwIP is a small independent implementation of the TCP/IP protocol suite. + +The focus of the lwIP TCP/IP implementation is to reduce the RAM usage +while still having a full scale TCP. This making lwIP suitable for use +in embedded systems with tens of kilobytes of free RAM and room for +around 40 kilobytes of code ROM. + +lwIP was originally developed by Adam Dunkels at the Computer and +Networks Architectures (CNA) lab at the Swedish Institute of Computer +Science (SICS) and is now developed and maintained by a worldwide +network of developers. + +FEATURES +-------- + +- IP (Internet Protocol, IPv4 and IPv6) including packet forwarding + over multiple network interfaces +- ICMP (Internet Control Message Protocol) for network maintenance and + debugging +- IGMP (Internet Group Management Protocol) for multicast traffic + management +- MLD (Multicast listener discovery for IPv6). Aims to be compliant + with RFC 2710. No support for MLDv2 +- ND (Neighbor discovery and stateless address autoconfiguration for + IPv6). Aims to be compliant with RFC 4861 (Neighbor discovery) and + RFC 4862 (Address autoconfiguration) +- DHCP, AutoIP/APIPA (Zeroconf), ACD (Address Conflict Detection) and + (stateless) DHCPv6 +- UDP (User Datagram Protocol) including experimental UDP-lite + extensions +- TCP (Transmission Control Protocol) with congestion control, RTT + estimation fast recovery/fast retransmit and sending SACKs +- raw/native API for enhanced performance +- Optional Berkeley-like socket API +- TLS: optional layered TCP (“altcp”) for nearly transparent TLS for + any TCP-based protocol (ported to mbedTLS) (see changelog for more + info) +- PPPoS and PPPoE (Point-to-point protocol over Serial/Ethernet) +- DNS (Domain name resolver incl. mDNS) +- 6LoWPAN (via IEEE 802.15.4, BLE or ZEP) + +APPLICATIONS +------------ + +- HTTP server with SSI and CGI (HTTPS via altcp) +- SNMPv2c agent with MIB compiler (Simple Network Management Protocol), + v3 via altcp +- SNTP (Simple network time protocol) +- NetBIOS name service responder +- MDNS (Multicast DNS) responder +- iPerf server implementation +- MQTT client (TLS support via altcp) + +LICENSE +------- + +lwIP is freely available under a BSD license. + +DEVELOPMENT +----------- + +lwIP has grown into an excellent TCP/IP stack for embedded devices, and +developers using the stack often submit bug fixes, improvements, and +additions to the stack to further increase its usefulness. + +Development of lwIP is hosted on Savannah, a central point for software +development, maintenance and distribution. Everyone can help improve +lwIP by use of Savannah’s interface, Git and the mailing list. A core +team of developers will commit changes to the Git source tree. + +The lwIP TCP/IP stack is maintained in the ‘lwip’ Git module and +contributions (such as platform ports) are in the ‘contrib’ Git module. + +See doc/savannah.txt for details on Git server access for users and +developers. + +The current Git trees are web-browsable: +http://git.savannah.gnu.org/cgit/lwip.git +http://git.savannah.gnu.org/cgit/lwip/lwip-contrib.git + +Submit patches and bugs via the lwIP project page: +http://savannah.nongnu.org/projects/lwip/ + +Continuous integration builds (GCC, clang): +https://travis-ci.org/lwip-tcpip/lwip + +DOCUMENTATION +------------- + +Self documentation of the source code is regularly extracted from the +current Git sources and is available from this web page: +http://www.nongnu.org/lwip/ + +Also, there are mailing lists you can subscribe at +http://savannah.nongnu.org/mail/?group=lwip plus searchable archives: +http://lists.nongnu.org/archive/html/lwip-users/ +http://lists.nongnu.org/archive/html/lwip-devel/ + +There is a wiki about lwIP at http://lwip.wikia.com/wiki/LwIP_Wiki You +might get questions answered there, but unfortunately, it is not as well +maintained as it should be. + +lwIP was originally written by Adam Dunkels: http://dunkels.com/adam/ + +Reading Adam’s papers, the files in docs/, browsing the source code +documentation and browsing the mailing list archives is a good way to +become familiar with the design of lwIP. + +Adam Dunkels adam@sics.se Leon Woestenberg leon.woestenberg@gmx.net diff --git a/Sming/Arch/Host/Components/lwip/.patches/lwip/README.txt b/Sming/Arch/Host/Components/lwip/.patches/lwip/README.txt new file mode 100644 index 0000000000..2eee6b639d --- /dev/null +++ b/Sming/Arch/Host/Components/lwip/.patches/lwip/README.txt @@ -0,0 +1,106 @@ +INTRODUCTION + +lwIP is a small independent implementation of the TCP/IP protocol suite. + +The focus of the lwIP TCP/IP implementation is to reduce the RAM usage +while still having a full scale TCP. This making lwIP suitable for use +in embedded systems with tens of kilobytes of free RAM and room for +around 40 kilobytes of code ROM. + +lwIP was originally developed by Adam Dunkels at the Computer and +Networks Architectures (CNA) lab at the Swedish Institute of Computer +Science (SICS) and is now developed and maintained by a worldwide +network of developers. + +FEATURES + +- IP (Internet Protocol, IPv4 and IPv6) including packet forwarding + over multiple network interfaces +- ICMP (Internet Control Message Protocol) for network maintenance and + debugging +- IGMP (Internet Group Management Protocol) for multicast traffic + management +- MLD (Multicast listener discovery for IPv6). Aims to be compliant + with RFC 2710. No support for MLDv2 +- ND (Neighbor discovery and stateless address autoconfiguration for + IPv6). Aims to be compliant with RFC 4861 (Neighbor discovery) and + RFC 4862 (Address autoconfiguration) +- DHCP, AutoIP/APIPA (Zeroconf), ACD (Address Conflict Detection) and + (stateless) DHCPv6 +- UDP (User Datagram Protocol) including experimental UDP-lite + extensions +- TCP (Transmission Control Protocol) with congestion control, RTT + estimation fast recovery/fast retransmit and sending SACKs +- raw/native API for enhanced performance +- Optional Berkeley-like socket API +- TLS: optional layered TCP ("altcp") for nearly transparent TLS for + any TCP-based protocol (ported to mbedTLS) (see changelog for more + info) +- PPPoS and PPPoE (Point-to-point protocol over Serial/Ethernet) +- DNS (Domain name resolver incl. mDNS) +- 6LoWPAN (via IEEE 802.15.4, BLE or ZEP) + +APPLICATIONS + +- HTTP server with SSI and CGI (HTTPS via altcp) +- SNMPv2c agent with MIB compiler (Simple Network Management + Protocol), v3 via altcp +- SNTP (Simple network time protocol) +- NetBIOS name service responder +- MDNS (Multicast DNS) responder +- iPerf server implementation +- MQTT client (TLS support via altcp) + +LICENSE + +lwIP is freely available under a BSD license. + +DEVELOPMENT + +lwIP has grown into an excellent TCP/IP stack for embedded devices, and +developers using the stack often submit bug fixes, improvements, and +additions to the stack to further increase its usefulness. + +Development of lwIP is hosted on Savannah, a central point for software +development, maintenance and distribution. Everyone can help improve +lwIP by use of Savannah's interface, Git and the mailing list. A core +team of developers will commit changes to the Git source tree. + +The lwIP TCP/IP stack is maintained in the 'lwip' Git module and +contributions (such as platform ports) are in the 'contrib' Git module. + +See doc/savannah.txt for details on Git server access for users and +developers. + +The current Git trees are web-browsable: +http://git.savannah.gnu.org/cgit/lwip.git +http://git.savannah.gnu.org/cgit/lwip/lwip-contrib.git + +Submit patches and bugs via the lwIP project page: +http://savannah.nongnu.org/projects/lwip/ + +Continuous integration builds (GCC, clang): +https://travis-ci.org/lwip-tcpip/lwip + +DOCUMENTATION + +Self documentation of the source code is regularly extracted from the +current Git sources and is available from this web page: +http://www.nongnu.org/lwip/ + +Also, there are mailing lists you can subscribe at +http://savannah.nongnu.org/mail/?group=lwip plus searchable archives: +http://lists.nongnu.org/archive/html/lwip-users/ +http://lists.nongnu.org/archive/html/lwip-devel/ + +There is a wiki about lwIP at http://lwip.wikia.com/wiki/LwIP\_Wiki You +might get questions answered there, but unfortunately, it is not as well +maintained as it should be. + +lwIP was originally written by Adam Dunkels: http://dunkels.com/adam/ + +Reading Adam's papers, the files in docs/, browsing the source code +documentation and browsing the mailing list archives is a good way to +become familiar with the design of lwIP. + +Adam Dunkels Leon Woestenberg diff --git a/Sming/Arch/Host/Components/lwip/README.rst b/Sming/Arch/Host/Components/lwip/README.rst new file mode 100644 index 0000000000..a3cb61e7cd --- /dev/null +++ b/Sming/Arch/Host/Components/lwip/README.rst @@ -0,0 +1,15 @@ +LWIP +==== + +Uses LWIP version 2 to enable networking for Sming running on a Windows or Linux Host system. + +Note that :envvar:`ENABLE_CUSTOM_LWIP` default is 2. Setting this to any other value will cause a build error. + +Options: + +.. envvar:: ENABLE_LWIPDEBUG + + 0 (default) + Standard build + 1 + Enable debugging output diff --git a/Sming/Arch/Host/Components/lwip/component.mk b/Sming/Arch/Host/Components/lwip/component.mk index 317e198468..13b608e616 100644 --- a/Sming/Arch/Host/Components/lwip/component.mk +++ b/Sming/Arch/Host/Components/lwip/component.mk @@ -2,8 +2,9 @@ CUSTOM_BUILD := 1 # => LWIP -ENABLE_CUSTOM_LWIP ?= 2 -ifneq ($(ENABLE_CUSTOM_LWIP), 2) +ifndef ENABLE_CUSTOM_LWIP +ENABLE_CUSTOM_LWIP := 2 +else ifneq ($(ENABLE_CUSTOM_LWIP), 2) $(error Host only supports LWIP version 2) endif diff --git a/Sming/Arch/Host/Components/sming-arch/README.rst b/Sming/Arch/Host/Components/sming-arch/README.rst new file mode 100644 index 0000000000..393d0e1dda --- /dev/null +++ b/Sming/Arch/Host/Components/sming-arch/README.rst @@ -0,0 +1,4 @@ +Sming (Host) +============ + +This Component builds a library containing architecture-specific code, and defines dependencies for Sming to build for the Host Emulator. diff --git a/Sming/Arch/Host/Components/spi_flash/README.rst b/Sming/Arch/Host/Components/spi_flash/README.rst new file mode 100644 index 0000000000..83f9356262 --- /dev/null +++ b/Sming/Arch/Host/Components/spi_flash/README.rst @@ -0,0 +1,6 @@ +SPI Flash +========= + +This Component emulates an embedded flash memory device using a backing file. It includes additional +checks on addresses, sizes and alignments to detect common issues which can be more difficult to find +when running on target hardware. diff --git a/Sming/Arch/Host/Components/vflash/README.rst b/Sming/Arch/Host/Components/vflash/README.rst new file mode 100644 index 0000000000..fb6761c0d1 --- /dev/null +++ b/Sming/Arch/Host/Components/vflash/README.rst @@ -0,0 +1,11 @@ +Virtual Flasher +=============== + +Flash memory access is emulated using :component-host:`spi_flash`, and this Component implements make targets to +operate on the flash backing file in a similar way to flashing a real device. + +The following options are interpreted and used to provide command-line paramters to the emulator executable: + +* ``FLASH_BIN``: full path to flash backing file +* ``SPI_SIZE``: Size of flash memory, e.g. 4M = 4MBytes, 512K = 512 KBytes, etc. +* ``HOST_FLASH_OPTIONS``: This defaults to a combination of the above variables, but you can override if necessary. diff --git a/Sming/Arch/Host/README.rst b/Sming/Arch/Host/README.rst new file mode 100644 index 0000000000..7def8d76a3 --- /dev/null +++ b/Sming/Arch/Host/README.rst @@ -0,0 +1,238 @@ +Sming Host Emulator +=================== + +.. highlight:: bash + +Summary +------- + +Allows Sming applications to be built as an executable to run on the +development host (Windows or Linux). + +This is a source-level emulator for developing and testing new framework +code prior to flashing a real device. + +This is not a machine emulator; if you need something operating at a +lower level take a look at `QEMU `__. + +Requirements +------------ + +``CMake`` is required to build LWIP + +Ensure you are using relatively recent compilers, with 32-bit libraries available. + +For Linux, you may require the ``gcc-multilib`` and ``g++-multilib`` +packages to build 32-bit executables on a 64-bit OS. + +For Windows, make sure your ``MinGW`` distro is up to date. If you run +``gcc --version`` you should get ``gcc (MinGW.org GCC-6.3.0-1) 6.3.0`` +or later. If it’s older, execute these commands: + +.. code-block:: powershell + + mingw-get update + mingw-get upgrade + +Building +-------- + +Build the framework and application as usual, specifying :envvar:`SMING_ARCH` =Host. For example: + +:: + + cd $SMING_HOME + make SMING_ARCH=Host + cd $SMING_HOME/../samples/Basic_Serial + make SMING_ARCH=Host + +This builds the application as an executable in, for example, +``out/Host/firmware/app.exe``. Various command-line options are +supported, use ``--help`` for details. + +The easiest way to run the emulator is via ``make run``. Variables are +used to pass the appropriate options (see `features`_). + +To find out what options are in force, use ``make list-config``. + +.. _features: + +Features +-------- + +Flash memory +~~~~~~~~~~~~ + +This is emulated using a backing file. By default it’s in ``flash.bin`` +in the firmware directory, you can change it by setting :envvar:`FLASH_BIN`. +The size of the flash memory is set via :envvar:`SPI_SIZE`. + +- ``make flashinit`` to clear and reset the file. +- ``make flashfs`` to copy the generated SPIFFS image into the backing file. +- ``make flash`` writes out all required images to the backing file. + For now, this is the same as ``make flashfs`` but that will change + when support is added for custom user images. + +UART (serial) ports +~~~~~~~~~~~~~~~~~~~ + +Multiple serial terminals are supported via raw TCP network sockets, so +telnet can be used to provide terminal capability. + +``make run`` starts the emulator with any required telnet sessions. By +default, no serial ports are enabled, however any output from UART0 is +redirected to the console. No input is possible. + +If your project requires proper terminal access, set +:envvar:`ENABLE_HOST_UARTID` to the UART numbers required. Typically this +would be added to the project’s ``component.mk`` file. For example, the +``Basic_Serial`` sample specifies ``ENABLE_HOST_UARTID=0 1`` to enable +emulation for both ``UART0`` and ``UART1``. + +Set :envvar:`HOST_UART_PORTBASE` if you want to change the base port number +used to communicate with the emulator. + +Alternatively, you can run the application manually like this: + +``out/firmware/app --pause --uart=0 --uart=1`` + +Now start a telnet session for each serial port, in separate command windows: + +:: + + telnet localhost 10000 + telnet localhost 10001 + +In the application window, press Enter. This behaviour is enabled by the +``pause`` option, which stops the emulator after initialisation so +telnet can connect to it. Without ``pause`` you’ll lose any serial +output at startup.) + +Note: For Windows users, ``putty`` is a good alternative to telnet. It +has options to for things like carriage-return/linefeed translation +(“\\n” -> “\\r\\n`”). Run using: + +:: + + putty telnet://localhost:10000 + +Port numbers are allocated sequentially from 10000. If you want to use +different port numbers, use ``--uartport`` option. + +Digital I/O +~~~~~~~~~~~ + +At present the emulator just writes output to the console. Inputs all return 0. + +Network +~~~~~~~ + +Linux +^^^^^ + +Support is provided via TAP network interface (a virtual network layer +operating at the ethernet frame level). A TAP interface must be created +first, and requires root priviledge: + +:: + + sudo ip tuntap add dev tap0 mode tap user `whoami` + sudo ip a a dev tap0 192.168.13.1/24 + sudo ifconfig tap0 up + +This creates the ``tap0`` interface. The emulator will automatically +select the first ``tap`` interface found. To override this, use the +``--ifname`` option. An IP address will be assigned, but can be changed +using the ``--ipaddr`` option. + +If your application needs to access the internet, additional setup is +required: + +:: + + sudo sysctl net.ipv4.ip_forward=1 + sudo sysctl net.ipv6.conf.default.forwarding=1 + sudo sysctl net.ipv6.conf.all.forwarding=1 + + export INTERNET_IF=wlan0 # http://www.adafruit.com/category/63_98 + +These displays use SPI to communicate, 4 or 5 pins are required to +interface + +Adafruit invests time and resources providing this open source code, +please support Adafruit and open-source hardware by purchasing +products from Adafruit! + +Written by Limor Fried/Ladyada for Adafruit Industries. +Scrolling code contributed by Michael Gregg +BSD license, check license.txt for more information +All text above must be included in any redistribution + +To download. click the DOWNLOADS button in the top right corner, rename the uncompressed folder Adafruit_SSD1306. Check that the Adafruit_SSD1306 folder contains Adafruit_SSD1306.cpp and Adafruit_SSD1306.h + +Place the Adafruit_SSD1306 library folder your /libraries/ folder. You may need to create the libraries subfolder if its your first library. Restart the IDE. + +You will also have to download the Adafruit GFX Graphics core which does all the circles, text, rectangles, etc. You can get it from +https://github.com/adafruit/Adafruit-GFX-Library +and download/install that library as well + + + +## Compatibility + +MCU | Tested Works | Doesn't Work | Not Tested | Notes +------------------ | :----------: | :----------: | :---------: | ----- +Atmega328 @ 16MHz | X | | | +Atmega328 @ 12MHz | X | | | +Atmega32u4 @ 16MHz | X | | | +Atmega32u4 @ 8MHz | X | | | +ESP8266 | X | | | change OLED_RESET to different pin if using default I2C pins D4/D5. +Atmega2560 @ 16MHz | X | | | +ATSAM3X8E | X | | | +ATSAM21D | X | | | +ATtiny85 @ 16MHz | | X | | +ATtiny85 @ 8MHz | | X | | +Intel Curie @ 32MHz | | | X | +STM32F2 | | | X | + + * ATmega328 @ 16MHz : Arduino UNO, Adafruit Pro Trinket 5V, Adafruit Metro 328, Adafruit Metro Mini + * ATmega328 @ 12MHz : Adafruit Pro Trinket 3V + * ATmega32u4 @ 16MHz : Arduino Leonardo, Arduino Micro, Arduino Yun, Teensy 2.0 + * ATmega32u4 @ 8MHz : Adafruit Flora, Bluefruit Micro + * ESP8266 : Adafruit Huzzah + * ATmega2560 @ 16MHz : Arduino Mega + * ATSAM3X8E : Arduino Due + * ATSAM21D : Arduino Zero, M0 Pro + * ATtiny85 @ 16MHz : Adafruit Trinket 5V + * ATtiny85 @ 8MHz : Adafruit Gemma, Arduino Gemma, Adafruit Trinket 3V + + diff --git a/Sming/Libraries/.patches/Adafruit_SSD1306/component.mk b/Sming/Libraries/.patches/Adafruit_SSD1306/component.mk new file mode 100644 index 0000000000..f2997c2408 --- /dev/null +++ b/Sming/Libraries/.patches/Adafruit_SSD1306/component.mk @@ -0,0 +1 @@ +COMPONENT_DEPENDS := Adafruit_GFX diff --git a/Sming/Libraries/.patches/Adafruit_ST7735/README.md b/Sming/Libraries/.patches/Adafruit_ST7735/README.md new file mode 100644 index 0000000000..51c739a72c --- /dev/null +++ b/Sming/Libraries/.patches/Adafruit_ST7735/README.md @@ -0,0 +1,28 @@ +# Adafruit ST7735 + +This is a library for the Adafruit 1.8" SPI display. +This library works with the Adafruit 1.8" TFT Breakout w/SD card + ----> http://www.adafruit.com/products/358 +The 1.8" TFT shield + ----> https://www.adafruit.com/product/802 +The 1.44" TFT breakout + ----> https://www.adafruit.com/product/2088 +as well as Adafruit raw 1.8" TFT display + ----> http://www.adafruit.com/products/618 + + +Check out the links above for our tutorials and wiring diagrams. +These displays use SPI to communicate, 4 or 5 pins are required +to interface (RST is optional). +Adafruit invests time and resources providing this open source code, +please support Adafruit and open-source hardware by purchasing +products from Adafruit! + +Written by Limor Fried/Ladyada for Adafruit Industries. +MIT license, all text above must be included in any redistribution + +To download. click the DOWNLOADS button in the top right corner, rename the uncompressed folder Adafruit_ST7735. Check that the Adafruit_ST7735 folder contains Adafruit_ST7735.cpp and Adafruit_ST7735. + +Place the Adafruit_ST7735 library folder your /libraries/ folder. You may need to create the libraries subfolder if its your first library. Restart the IDE + +Also requires the Adafruit_GFX library for Arduino. diff --git a/Sming/Libraries/.patches/Adafruit_ST7735/component.mk b/Sming/Libraries/.patches/Adafruit_ST7735/component.mk new file mode 100644 index 0000000000..f2997c2408 --- /dev/null +++ b/Sming/Libraries/.patches/Adafruit_ST7735/component.mk @@ -0,0 +1 @@ +COMPONENT_DEPENDS := Adafruit_GFX diff --git a/Sming/Libraries/.patches/HMC5883L/component.mk b/Sming/Libraries/.patches/HMC5883L/component.mk new file mode 100644 index 0000000000..725f8abd75 --- /dev/null +++ b/Sming/Libraries/.patches/HMC5883L/component.mk @@ -0,0 +1 @@ +COMPONENT_DEPENDS := I2Cdev diff --git a/Sming/Libraries/.patches/IR/component.mk b/Sming/Libraries/.patches/IR/component.mk new file mode 100644 index 0000000000..2de8793d0e --- /dev/null +++ b/Sming/Libraries/.patches/IR/component.mk @@ -0,0 +1,2 @@ +COMPONENT_DEPENDS := RingBufCPP +COMPONENT_DOCFILES := .github/Contributors.md diff --git a/Sming/Libraries/.patches/ITEADLIB_Arduino_Nextion/README.rst b/Sming/Libraries/.patches/ITEADLIB_Arduino_Nextion/README.rst new file mode 100644 index 0000000000..c7b1b282ca --- /dev/null +++ b/Sming/Libraries/.patches/ITEADLIB_Arduino_Nextion/README.rst @@ -0,0 +1,131 @@ +Nextion +======= + +Introduction +------------ + +Nextion Arduino library provides an easy-to-use way to manipulate +Nextion serial displays. Users can use the libarry freely, either in +commerical projects or open-source prjects, without any additional +condiitons. + +| For more information about the Nextion display project, please visit + `the wiki。 `__ +| The wiki provdies all the necessary technical documnets, quick start + guide, tutorials, demos, as well as some useful resources. + +To get your Nextion display, please visit +`iMall. `__ + +To discuss the project? Request new features? Report a BUG? please visit +the `Forums `__ + +Download Source Code +-------------------- + +Latest version is unstable and a mass of change may be applied in a +short time without any notification for users. Commonly, it is for +developers of this library. + +**Release version is recommanded for you, unless you are one of +developers of this library.** + +**Release notes** is at +https://github.com/itead/ITEADLIB_Arduino_Nextion/blob/master/release_notes.md. + +Latest(unstable) +~~~~~~~~~~~~~~~~ + +Latest source code(master branch) can be downloaded: +https://github.com/itead/ITEADLIB_Arduino_Nextion/archive/master.zip. + +You can also clone it via git: + +:: + + git clone https://github.com/itead/ITEADLIB_Arduino_Nextion + +Releases(stable) +~~~~~~~~~~~~~~~~ + +- https://github.com/itead/ITEADLIB_Arduino_Nextion/archive/v0.7.0.zip +- https://github.com/itead/ITEADLIB_Arduino_Nextion/archive/v0.7.0.tar.gz + +All releases can be available from: +https://github.com/itead/ITEADLIB_Arduino_Nextion/releases. + +Documentation +------------- + +Offline Documentation’s entry ``doc/Documentation/index.html`` shiped +with source code can be open in your browser such as Chrome, Firefox or +any one you like. + +Suppported Mainboards +--------------------- + +**All boards, which has one or more hardware serial, can be supported.** + +For example: + +- Iteaduino MEGA2560 +- Iteaduino UNO +- Arduino MEGA2560 +- Arduino UNO + +Configuration +------------- + +In configuration file NexConfig.h, you can find two macros below: + +- dbSerial: Debug Serial (baudrate:9600), needed by beginners for debug + your nextion applications or sketches. If your complete your work, it + will be a wise choice to disable Debug Serial. + +- nexSerial: Nextion Serial, the bridge of Nextion and your mainboard. + +**Note:** the default configuration is for MEGA2560. + +Redirect dbSerial and nexSerial +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you want to change the default serial to debug or communicate with +Nextion , you need to modify the line in configuration file: + +:: + + #define dbSerial Serial ---> #define dbSerial Serialxxx + #define nexSerial Serial2 ---> #define nexSeria Serialxxx + +Disable Debug Serial +~~~~~~~~~~~~~~~~~~~~ + +If you want to disable the debug information,you need to modify the line +in configuration file: + +:: + + #define DEBUG_SERIAL_ENABLE ---> //#define DEBUG_SERIAL_ENABLE + +UNO-like Mainboards +------------------- + +If your board has only one hardware serial, such as UNO, you should +disable dbSerial and redirect nexSerial to Serial(Refer to +section:\ ``Serial configuration``). + +Useful Links +------------ + +http://blog.iteadstudio.com/nextion-tutorial-based-on-nextion-arduino-library/ + +License +------- + + The MIT License (MIT) + + Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/Sming/Libraries/.patches/MCP_CAN_lib.patch b/Sming/Libraries/.patches/MCP_CAN_lib.patch new file mode 100644 index 0000000000..e25851a8f0 --- /dev/null +++ b/Sming/Libraries/.patches/MCP_CAN_lib.patch @@ -0,0 +1,32 @@ +diff --git a/README.md b/README.md +index 291a1d0..8886c79 100644 +--- a/README.md ++++ b/README.md +@@ -1,5 +1,5 @@ +-MCP_CAN Library for Arduino +-============== ++# MCP_CAN Library for Arduino ++ + MCP_CAN library v1.5 + This library is compatible with any shield or board that uses the MCP2515 or MCP25625 CAN protocol controller. + +@@ -24,15 +24,15 @@ Using the setMode() function the sketch can now put the protocol controller into + + User can enable and disable (default) One-Shot transmission mode from the sketch using enOneShotTX() or disOneShotTX() respectively. + +-Installation +-============== ++## Installation ++ + Copy this into the "[.../MySketches/]libraries/" folder and restart the Arduino editor. + + NOTE: If an older version of the library exists (e.g. CAN_BUS_Shield) be sure to remove it from the libraries folder or replace the files with those in this library to avoid conflicts. + + +-Help and Support +-============== ++## Help and Support ++ + This is primarily for non-bug related issues: Please start a *new thread* in an appropriate area at Seeedstudio forums or Arduino.cc forums and then send me (coryjfowler) a link through the PM system, my user name is the same as it is here. I will receive an email about the PM and generally get to it with-in a week or less. Keep in mind, I do this in my spare time. + + diff --git a/Sming/Libraries/AM2321/README.md b/Sming/Libraries/AM2321/README.md index 03fadefe15..43df77f60d 100644 --- a/Sming/Libraries/AM2321/README.md +++ b/Sming/Libraries/AM2321/README.md @@ -1,7 +1,7 @@ # AM2321 -- AM2321 sensor support for Arduino. -- More: http://playground.arduino.cc/Main/AM2321 +- AM2321 sensor support for Arduino. +- See [Arduino AM2321](http://playground.arduino.cc/Main/AM2321) ## Example: diff --git a/Sming/Libraries/APA102/README.rst b/Sming/Libraries/APA102/README.rst new file mode 100644 index 0000000000..ed28df7b16 --- /dev/null +++ b/Sming/Libraries/APA102/README.rst @@ -0,0 +1,9 @@ +APA102 LED +========== + +APA102 library by HappyCodingRobot@github.com + +APA102 class enhanced to work with hardware SPI and software SPI. +Changed to work with the new SPI implementation. + +See :pull-request:`787`. diff --git a/Sming/Libraries/Adafruit_GFX/README.txt b/Sming/Libraries/Adafruit_GFX/README.md similarity index 97% rename from Sming/Libraries/Adafruit_GFX/README.txt rename to Sming/Libraries/Adafruit_GFX/README.md index 52e1d5d4a6..065a38d305 100644 --- a/Sming/Libraries/Adafruit_GFX/README.txt +++ b/Sming/Libraries/Adafruit_GFX/README.md @@ -1,3 +1,5 @@ +# Adafruit GFX + This is the core graphics library for all our displays, providing a common set of graphics primitives (points, lines, circles, etc.). It needs to be paired with a hardware-specific library for each display device we carry (to handle the lower-level functions). Adafruit invests time and resources providing this open source code, please support Adafruit and open-source hardware by purchasing products from Adafruit! @@ -10,8 +12,7 @@ To download, click the DOWNLOAD ZIP button, uncompress and rename the uncompress Place the Adafruit_GFX library folder your /Libraries/ folder. You may need to create the Libraries subfolder if its your first library. Restart the IDE. -Useful Resources -================ +## Useful Resources - Image2Code This is a handy Java GUI utility to convert a BMP file into the array code necessary to display the image with the drawBitmap function. Check out the code at ehubin's GitHub repository: diff --git a/Sming/Libraries/Adafruit_ILI9341/README.txt b/Sming/Libraries/Adafruit_ILI9341/README.md similarity index 98% rename from Sming/Libraries/Adafruit_ILI9341/README.txt rename to Sming/Libraries/Adafruit_ILI9341/README.md index 7c59050147..1307e60f0c 100644 --- a/Sming/Libraries/Adafruit_ILI9341/README.txt +++ b/Sming/Libraries/Adafruit_ILI9341/README.md @@ -1,3 +1,5 @@ +# Adafruit ILI9341 + This is a library for the Adafruit ILI9341 display products This library works with the Adafruit 2.8" Touch Shield V2 (SPI) diff --git a/Sming/Libraries/Adafruit_NeoPixel/README.md b/Sming/Libraries/Adafruit_NeoPixel/README.md new file mode 100644 index 0000000000..fbeff35504 --- /dev/null +++ b/Sming/Libraries/Adafruit_NeoPixel/README.md @@ -0,0 +1,50 @@ +# Adafruit NeoPixel Library +[![Build Status](https://travis-ci.org/adafruit/Adafruit_NeoPixel.svg?branch=master)](https://travis-ci.org/adafruit/Adafruit_NeoPixel) + +*This library edited and adapted for Sming project by alonewolfx2 alonewolf07@gmail.com* + +Arduino library for controlling single-wire-based LED pixels and strip such as the [Adafruit 60 LED/meter Digital LED strip][strip], the [Adafruit FLORA RGB Smart Pixel][flora], the [Adafruit Breadboard-friendly RGB Smart Pixel][pixel], the [Adafruit NeoPixel Stick][stick], and the [Adafruit NeoPixel Shield][shield]. + +After downloading, rename folder to 'Adafruit_NeoPixel' and install in Arduino Libraries folder. Restart Arduino IDE, then open File->Sketchbook->Library->Adafruit_NeoPixel->strandtest sketch. + +Compatibility notes: Port A is not supported on any AVR processors at this time + +[flora]: http://adafruit.com/products/1060 +[strip]: http://adafruit.com/products/1138 +[pixel]: http://adafruit.com/products/1312 +[stick]: http://adafruit.com/products/1426 +[shield]: http://adafruit.com/products/1430 + +--- + +## Supported chipsets + +We have included code for the following chips - *sometimes these break for exciting reasons that we can't control* in which case please open an issue! + + * AVR ATmega and ATtiny (any 8-bit) - 8 MHz, 12 MHz and 16 MHz + * Teensy 3.x and LC + * Arduino Due + * Arduino 101 + * ATSAMD21 (Arduino Zero/M0 and other SAMD21 boards) @ 48 MHz + * ATSAMD51 @ 120 MHz + * Adafruit STM32 Feather @ 120 MHz + * ESP8266 any speed + * ESP32 any speed + * Nordic nRF52 (Adafruit Feather nRF52), nRF51 (micro:bit) + +Check forks for other architectures not listed here! + +--- + +### Roadmap + +The PRIME DIRECTIVE is to maintain backward compatibility with existing Arduino sketches -- many are hosted elsewhere and don't track changes here, some are in print and can never be changed! + +Please don't reformat code for the sake of reformatting code. The resulting large "visual diff" makes it impossible to untangle actual bug fixes from merely rearranged lines. (Exception for first item in wishlist below.) + +Things I'd Like To Do But There's No Official Timeline So Please Don't Count On Any Of This Ever Being Canonical: + + * For the show() function (with all the delicate pixel timing stuff), break out each architecture into separate source files rather than the current unmaintainable tangle of #ifdef statements! + * Please don't use updateLength() or updateType() in new code. They should not have been implemented this way (use the C++ 'new' operator with the regular constructor instead) and are only sticking around because of the Prime Directive. setPin() is OK for now though, it's a trick we can use to 'recycle' pixel memory across multiple strips. + * In the M0 and M4 code, use the hardware systick counter for bit timing rather than hand-tweaked NOPs (a temporary kludge at the time because I wasn't reading systick correctly). (As of 1.4.2, systick is used on M4 devices and it appears to be overclock-compatible. Not for M0 yet, which is why this item is still here.) + * As currently written, brightness scaling is still a "destructive" operation -- pixel values are altered in RAM and the original value as set can't be accurately read back, only approximated, which has been confusing and frustrating to users. It was done this way at the time because NeoPixel timing is strict, AVR microcontrollers (all we had at the time) are limited, and assembly language is hard. All the 32-bit architectures should have no problem handling nondestructive brightness scaling -- calculating each byte immediately before it's sent out the wire, maintaining the original set value in RAM -- the work just hasn't been done. There's a fair chance even the AVR code could manage it with some intense focus. (The DotStar library achieves nondestructive brightness scaling because it doesn't have to manage data timing so carefully...every architecture, even ATtiny, just takes whatever cycles it needs for the multiply/shift operations.) diff --git a/Sming/Libraries/Adafruit_PCD8544/README.txt b/Sming/Libraries/Adafruit_PCD8544/README.md similarity index 98% rename from Sming/Libraries/Adafruit_PCD8544/README.txt rename to Sming/Libraries/Adafruit_PCD8544/README.md index d75f7300fc..0aa9227408 100644 --- a/Sming/Libraries/Adafruit_PCD8544/README.txt +++ b/Sming/Libraries/Adafruit_PCD8544/README.md @@ -1,3 +1,5 @@ +# Adafruit PCD8544 + This is a library for our Monochrome Nokia 5110 LCD Displays Pick one up today in the adafruit shop! diff --git a/Sming/Libraries/ArduCAM/README.md b/Sming/Libraries/ArduCAM/README.md new file mode 100644 index 0000000000..5c9d019240 --- /dev/null +++ b/Sming/Libraries/ArduCAM/README.md @@ -0,0 +1,94 @@ +# ArduCAM Library + +## Introduction + +This is a opensource library for taking high resolution still images and short video clip on Arduino based platforms using ArduCAM's camera moduels.
+The camera breakout boards should work with ArduCAM shield before connecting to the Arduino boards.
+ArduCAM mini series camera modules like Mini-2MP, Mini-5MP(Plus) can be connected to Arduino boards directly.
+In addition to Arduino, the library can be ported to any hardware platforms as long as they have I2C and SPI interface based on this ArduCAM library.
+ +### Now Supported Cameras +- OV7660 0.3MP +- OV7670 0.3MP +- OV7675 0.3MP +- OV7725 0.3MP +- MT9V111 0.3MP +- MT9M112 1.3MP +- MT9M001 1.3MP +- MT9D111 2MP +- OV2640 2MP JPEG +- MT9T112 3MP +- OV3640 3MP +- OV5642 5MP JPEG +- OV5640 5MP JPEG + +### Supported MCU Platform +- Theoretically support all Arduino families +- Arduino UNO R3 (Tested) +- Arduino MEGA2560 R3 (Tested) +- Arduino Leonardo R3 (Tested) +- Arduino Nano (Tested) +- Arduino DUE (Tested) +- Arduino Genuion 101 (Tested) +- Raspberry Pi (Tested) +- ESP8266-12 (Tested) (http://www.arducam.com/downloads/ESP8266_UNO/package_ArduCAM_index.json) +* Feather M0 (Tested with OV5642) + +Note: ArduCAM library for ESP8266 is maintained in another repository [ESP8266](https://github.com/ArduCAM/ArduCAM_ESP8266_UNO) using a json board manager script.
+ +### Libraries Structure +The basic libraries are composed by two sub-libraries one is ArduCAM and the other is UTFT4ArduCAM_SPI. These two libraries should be copied right under the libraries of Arduino directory in order to be recognized by the Arduino IDE.
+The ArduCAM library is the core library for ArduCAM shields. It contains supported image sensor drivers and user land API functions which issue capture or image data read commands .There is also an example directory inside the ArduCAM library which illustrates most +function of the ArduCAM shields. The existing examples are plug and play without need to write a single line of code.
+The UTFT4ArduCAM_SPI library is modified version of UTFT which is written by [Henning Karlsen](http://www.henningkarlsen.com/electronics). We ported it to support ArduCAM +shield with LCD screen. So the UTFT4ArduCAM_SPI library is only needed when using the ArduCAM-LF model.
+ +## How to use +The libraries should be configured before running any examples, or else you will get a compilation error message.
+ +### 1. Edit memorysaver.h file +Open the `memorysaver.h` file in the ArduCAM folder and enable the hardware platform and camera module which matches to your hardware by comment or +uncomment the macro definition in the file. For example, if you got a ArduCAM-Mini-2MP you +should uncomment the line `#define OV2640_MINI_2MP` and comment all the other lines. And +if you got a ArduCAM-Shield-V2 and a OV5642 camera module, you should uncomment the line `#define ARDUCAM_SHIELD_V2` +and the line `#define OV5642_CAM` then comment other lines.
+ +### 2. Choose correct CS pin for your camera +Open one of the examples, wiring SPI and I2C interface especially CS pins to ArduCAM shield according to the examples. +Hardware and software shuld be consistent to run the examples correctly. + +### 3. Upload the examples +In the example folder there are seven sub directories for different ArduCAM models and the host application. +The `Mini` folder is for ArduCAM-Mini-2MP and ArduCAM-Mini-5MP modules.
+The `Mini_5MP_Plus` folder is for ArduCAM-Mini-5MP-Plus (OV5640/OV5642) modules.
+The `RevC` folder is for ArduCAM-Shield-RevC or ArduCAM-Shield-RevC+ shields.
+The `Shield_V2` folder is for ArduCAM-Shield-V2 shield.
+The `host_app` folder is host capture and display application for all of ArduCAM modules.
+The `RaspberryPi` folder is examples used for Raspberry Pi platform, see [more instruction](https://github.com/ArduCAM/Arduino/tree/master/ArduCAM/examples/RaspberryPi).
+The `ESP8266` folder is for ArduCAM-ESP8266-UNO board examples for library compatibility. Please try repository [ESP8266](https://github.com/ArduCAM/ArduCAM_ESP8266_UNO) using josn board manager script instead.
+Selecting correct COM port and Arduino boards then upload the sketches.
+ +## Arducam MINI Camera Demo Tutorial for Arduino + +[![IMAGE ALT TEXT](https://github.com/UCTRONICS/pic/blob/master/Arducam_MINI_Camera.jpeg)](https://youtu.be/hybQpjwJ4aA "Arducam MINI Camera Demo Tutorial for Arduino") + +## Arducam Camera Shield V2 Demo Tutorial for Arduino + +[![IMAGE ALT TEXT](https://github.com/UCTRONICS/pic/blob/master/Arducam_Shield_V2_Camera.jpeg)](https://youtu.be/XMik38TNqGk "Arducam MINI Camera Demo Tutorial for Arduino") + +### 4. How To Connect Bluetooth Module +- Using this demo + +```Bash +https://github.com/ArduCAM/Arduino/blob/master/ArduCAM/examples/mini/ArduCAM_Mini_Video_Streaming_Bluetooth/ArduCAM_Mini_Video_Streaming_Bluetooth.ino +``` + + ![Alt text](https://github.com/ArduCAM/Arduino/blob/master/Arducam_Mini_VideoStreaming_BlueTooth.png) + +## 5. How to download the Host V2 ? + +- For ArduCAM_Host_V2.0_Mac.app, please refer to this link: +https://www.arducam.com/downloads/app/ArduCAM_Host_V2.0_Mac.app.zip + +- For ArduCAM_Mini_V2.0_Linux_x86_64bit, Please refer to this link: +https://www.arducam.com/downloads/app/ArduCAM_Mini_V2.0_Linux_x86_64bit.zip diff --git a/Sming/Libraries/ArduinoJson5/README.rst b/Sming/Libraries/ArduinoJson5/README.rst new file mode 100644 index 0000000000..4b25ba83b9 --- /dev/null +++ b/Sming/Libraries/ArduinoJson5/README.rst @@ -0,0 +1,4 @@ +ArduinoJson Version 5 +===================== + +Provided to support existing applications. New projects should use :library:`ArduinoJson6` diff --git a/Sming/Libraries/ArduinoJson6/README.rst b/Sming/Libraries/ArduinoJson6/README.rst new file mode 100644 index 0000000000..6e9504d8f8 --- /dev/null +++ b/Sming/Libraries/ArduinoJson6/README.rst @@ -0,0 +1,22 @@ +ArduinoJson Version 6 +===================== + +If you're upgrading from :library:`version 5 `, some changes will be required to your code. +See the `Version 6 Migration Guide `__ for details. + +Some methods of ``JsonVariant`` have been removed, replacements are: + +``asString()`` -> ``as()`` or ``as``. Note that ``as`` produces a +serialized version, so you’ll get “null” instead of an empty/invalid result String. + +``asArray()`` -> ``as()`` + +``asObject()`` -> ``as()`` + + +There are also some useful helper functions available in the ``Json`` namespace. See ``Libraries/ArduinoJson6/include/ArduinoJson.h``. + +Sming definitions +----------------- + +:cpp:class:`JsonObjectStream` diff --git a/Sming/Libraries/BH1750FVI/README.md b/Sming/Libraries/BH1750FVI/README.md new file mode 100644 index 0000000000..5af39e30ca --- /dev/null +++ b/Sming/Libraries/BH1750FVI/README.md @@ -0,0 +1,46 @@ +BH1750FVI_Master +================ + +https://github.com/Genotronex/BH1750FVI_Master.git + +Digital Light Sensor BH1750 + +/* + This is a simple code to test BH1750FVI Light senosr + + communicate using I2C Protocol + + this library enable 2 slave device address + + Main address 0x23 + + secondary address 0x5C + + connect this sensor as following : + + VCC >>> 3.3V + + SDA >>> A4 + + SCL >>> A5 + + addr >> A3 "Optional and use address 0x23 " + + Gnd >>>Gnd + + + + please after download this library unzip and rename it to BH1750FVI and put it in the libraries folder in the arduino path , then restart Arduino IDE + + + Written By : Mohannad Rawashdeh + + 26/9/2013 + + for more information : http://www.instructables.com/id/BH1750-Digital-Light-Sensor/ + + contact me on my email + + genotronex@gmail.com + */ + diff --git a/Sming/Libraries/BMP180/README.md b/Sming/Libraries/BMP180/README.md new file mode 100644 index 0000000000..f020c369b0 --- /dev/null +++ b/Sming/Libraries/BMP180/README.md @@ -0,0 +1,5 @@ +# BMP180 + +Arduino library for BMP180 Bosch pressure/temperature sensor + +Copyright (C) 2012 Love Electronics Ltd (loveelectronics.com) diff --git a/Sming/Libraries/Bounce/documentation.txt b/Sming/Libraries/Bounce/README.md similarity index 88% rename from Sming/Libraries/Bounce/documentation.txt rename to Sming/Libraries/Bounce/README.md index 3a0ad2d92d..740e1874ce 100644 --- a/Sming/Libraries/Bounce/documentation.txt +++ b/Sming/Libraries/Bounce/README.md @@ -1,4 +1,4 @@ -Bounce library for Arduino +# Bounce library for Arduino Version 1.6 diff --git a/Sming/Libraries/CapacitiveSensor/README.md b/Sming/Libraries/CapacitiveSensor/README.md index df453482fa..209e1b300a 100644 --- a/Sming/Libraries/CapacitiveSensor/README.md +++ b/Sming/Libraries/CapacitiveSensor/README.md @@ -1,4 +1,4 @@ -#CapacitiveSensor Library# +# CapacitiveSensor Library CapacitiveSensor lets you create sensors that can detect touch or proximity. diff --git a/Sming/Libraries/DS18S20/README.md b/Sming/Libraries/DS18S20/README.md new file mode 100644 index 0000000000..c4e535c216 --- /dev/null +++ b/Sming/Libraries/DS18S20/README.md @@ -0,0 +1,8 @@ +# DS18S20 Temperature Sensor + +This library provides access to DS18S20 temperature sensors connected via 1-Wire bus to a single GPIO +The DS18S20 can run in several modes, with varying degrees of resolution. The highest resolution is 12-bit which provides 0.0625C resolution. +12-bit measurement takes 750ms. With 4 sensors connected, measurement will take 3s. + +Created on: 01-09-2015 +Author: flexiti and Anakod diff --git a/Sming/Libraries/DS3232RTC/README.rst b/Sming/Libraries/DS3232RTC/README.rst new file mode 100644 index 0000000000..530c7528b0 --- /dev/null +++ b/Sming/Libraries/DS3232RTC/README.rst @@ -0,0 +1,902 @@ +Arduino DS3232RTC Library v1.0 +============================== + +| https://github.com/JChristensen/DS3232RTC ReadMe file +| Jack Christensen Mar 2013 + +.. figure:: http://mirrors.creativecommons.org/presskit/buttons/80x15/png/by-sa.png + :alt: CC BY-SA + + CC BY-SA + +Introduction +------------ + +**DS3232RTC** is an Arduino library that supports the Maxim Integrated +DS3232 and DS3231 Real-Time Clocks. This library is intended to be used +with the `Arduino Time +library `__. + +The **DS3232RTC** library is a drop-in replacement for the DS1307RTC.h +library by Michael Margolis that is supplied with the Arduino Time +library above. To change from using a DS1307 RTC to an DS323x RTC, it is +only necessary to use ``#include `` instead of +``#include ``. + +This library is **not** a drop-in replacement for `PJRC’s newer version +of the DS1307RTC +library `__. + +**DS3232RTC** also implements functions to support the additional +features of the DS3232 and DS3231. The DS3231 has the same features as +the DS3232 except: (1) Battery-backed SRAM, (2) Battery-backed 32kHz +output (BB32kHz bit in Control/Status register 0x0F), and (3) Adjustable +temperature sensor sample rate (CRATE1:0 bits in the Control/Status +register). + +“Arduino DS3232RTC Library” by Jack Christensen is licensed under CC +BY-SA 4.0. + +Installation +------------ + +To use the **DS3232RTC** library: + +- Go to https://github.com/JChristensen/DS3232RTC, click the + **Download ZIP** button and save the ZIP file to a convenient location + on your PC. +- Uncompress the downloaded file. This will result in a + folder containing all the files for the library, that has a name that + includes the branch name, usually **DS3232RTC-master**. +- Rename the folder to just **DS3232RTC**. +- Copy the renamed folder to the Arduino sketchbook\\libraries folder. + +Examples +-------- + +The following example sketches are included with the **DS3232RTC** +library: + +SetSerial + Set the RTC’s date and time from the Arduino + serial monitor. Displays date, time and temperature. + +TimeRTC + Same as the example of the same name provided with the **Time** library, + demonstrating the interchangeability of the **DS3232RTC** library with + the **DS1307RTC** library. - **tiny3232_KnockBang:** Demonstrates + interfacing an ATtiny45/85 to a DS3231 or DS3232 RTC. + +Usage notes +----------- + +When using the **DS3232RTC** library, the user is responsible for +ensuring that reads and writes do not exceed the device’s address space +(0x00-0x12 for DS3231, 0x00-0xFF for DS3232); no bounds checking is done +by the library. + +Similar to the **DS1307RTC** library, the **DS3232RTC** library +instantiates an RTC object; the user does not need to do this. + +To use the **DS3232RTC** library, the Time and Wire libraries must also +be included. For brevity, these includes are not repeated in the +examples below: + +.. code:: cpp + + #include //http://github.com/JChristensen/DS3232RTC + #include //http://www.arduino.cc/playground/Code/Time + #include //http://arduino.cc/en/Reference/Wire (included with Arduino IDE) + +Enumerations +------------ + +SQWAVE_FREQS_t +~~~~~~~~~~~~~~ + +Description +^^^^^^^^^^^ + +Symbolic names used with the squareWave() method (described below). + +Values +^^^^^^ + +- SQWAVE_NONE +- SQWAVE_1_HZ +- SQWAVE_1024_HZ +- SQWAVE_4096_HZ +- SQWAVE_8192_HZ + +ALARM_TYPES_t +~~~~~~~~~~~~~ + +.. _description-1: + +Description +^^^^^^^^^^^ + +Symbolic names used with the setAlarm() method (described below). + +Values for Alarm 1 +^^^^^^^^^^^^^^^^^^ + +- ALM1_EVERY_SECOND – causes an alarm once per second. +- ALM1_MATCH_SECONDS – causes an alarm when the seconds match + (i.e. once per minute). +- ALM1_MATCH_MINUTES – causes an alarm when the minutes *and* seconds + match. +- ALM1_MATCH_HOURS – causes an alarm when the hours *and* minutes *and* + seconds match. +- ALM1_MATCH_DATE – causes an alarm when the date of the month *and* + hours *and* minutes *and* seconds match. +- ALM1_MATCH_DAY – causes an alarm when the day of the week *and* hours + *and* minutes *and* seconds match. + +Values for Alarm 2 +^^^^^^^^^^^^^^^^^^ + +- ALM2_EVERY_MINUTE – causes an alarm once per minute. +- ALM2_MATCH_MINUTES – causes an alarm when the minutes match + (i.e. once per hour). +- ALM2_MATCH_HOURS – causes an alarm when the hours *and* minutes + match. +- ALM2_MATCH_DATE – causes an alarm when the date of the month *and* + hours *and* minutes match. +- ALM2_MATCH_DAY – causes an alarm when the day of the week *and* hours + *and* minutes match. + +Methods for setting and reading the time +---------------------------------------- + +get(void) +~~~~~~~~~ + +.. _description-2: + +Description +^^^^^^^^^^^ + +Reads the current date and time from the RTC and returns it as a +*time_t* value. Returns zero if an I2C error occurs (RTC not present, +etc.). + +Syntax +^^^^^^ + +``RTC.get();`` + +Parameters +^^^^^^^^^^ + +None. + +Returns +^^^^^^^ + +Current date and time *(time_t)* + +Example +^^^^^^^ + +.. code:: cpp + + time_t myTime; + myTime = RTC.get(); + +set(time_t t) +~~~~~~~~~~~~~ + +.. _description-3: + +Description +^^^^^^^^^^^ + +Sets the RTC date and time to the given *time_t* value. Clears the +oscillator stop flag (OSF) bit in the control/status register. See the +``oscStopped()`` function and also the DS323x datasheet for more +information on the OSF bit. + +.. _syntax-1: + +Syntax +^^^^^^ + +``RTC.set(t);`` + +.. _parameters-1: + +Parameters +^^^^^^^^^^ + +t + The date and time to set the RTC to *(time_t)* + +.. _returns-1: + +Returns +^^^^^^^ + +I2C status *(byte)*. Returns zero if successful. + +.. _example-1: + +Example +^^^^^^^ + +.. code:: cpp + + //this example first sets the system time (maintained by the Time library) to + //a hard-coded date and time, and then sets the RTC from the system time. + //the setTime() function is part of the Time library. + setTime(23, 31, 30, 13, 2, 2009); //set the system time to 23h31m30s on 13Feb2009 + RTC.set(now()); //set the RTC from the system time + +read(tmElements_t &tm) +~~~~~~~~~~~~~~~~~~~~~~ + +.. _description-4: + +Description +^^^^^^^^^^^ + +Reads the current date and time from the RTC and returns it as a +*tmElements_t* structure. See the `Arduino Time +library `__ for details on +the *tmElements_t* structure. + +.. _syntax-2: + +Syntax +^^^^^^ + +``RTC.read(tm);`` + +.. _parameters-2: + +Parameters +^^^^^^^^^^ + +tm + Address of a *tmElements_t* structure to which the date and time are returned. + +.. _returns-2: + +Returns +^^^^^^^ + +I2C status *(byte)*. Returns zero if successful. The date and time read +from the RTC are returned to the **tm** parameter. + +.. _example-2: + +Example +^^^^^^^ + +.. code:: cpp + + tmElements_t tm; + RTC.read(tm); + Serial.print(tm.Hour, DEC); + Serial.print(':'); + Serial.print(tm.Minute,DEC); + Serial.print(':'); + Serial.println(tm.Second,DEC); + +write(tmElements_t &tm) +~~~~~~~~~~~~~~~~~~~~~~~ + +.. _description-5: + +Description +^^^^^^^^^^^ + +Sets the RTC to the date and time given by a *tmElements_t* structure. +Clears the oscillator stop flag (OSF) bit in the control/status +register. See the ``oscStopped()`` function and also the DS323x +datasheet for more information on the OSF bit. + +.. _syntax-3: + +Syntax +^^^^^^ + +``RTC.write(tm);`` + +.. _parameters-3: + +Parameters +^^^^^^^^^^ + +tm + Address of a *tmElements_t* structure used to set the date and time. + +.. _returns-3: + +Returns +^^^^^^^ + +I2C status *(byte)*. Returns zero if successful. + +.. _example-3: + +Example +^^^^^^^ + +.. code:: cpp + + tmElements_t tm; + tm.Hour = 23; //set the tm structure to 23h31m30s on 13Feb2009 + tm.Minute = 31; + tm.Minute = 30; + tm.Day = 13; + tm.Month = 2; + tm.Year = 2009 - 1970; //tmElements_t.Year is the offset from 1970 + RTC.write(tm); //set the RTC from the tm structure + +Methods for reading and writing RTC registers or static RAM (SRAM) for the DS3232 +--------------------------------------------------------------------------------- + +The DS3232RTC.h file defines symbolic names for the timekeeping, alarm, +status and control registers. These can be used for the addr argument in +the functions below. + +writeRTC(byte addr, byte \*values, byte nBytes) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _description-6: + +Description +^^^^^^^^^^^ + +Write one or more bytes to RTC memory. + +.. _syntax-4: + +Syntax +^^^^^^ + +``RTC.writeRTC(addr, values, nbytes);`` + +.. _parameters-4: + +Parameters +^^^^^^^^^^ + +addr + First SRAM address to write *(byte)*. The valid address range + is 0x00-0x12 for DS3231, 0x00-0xFF for DS3232. The general-purpose SRAM + for the DS3232 begins at address 0x14. Address is not checked for + validity by the library. + +values + An array of values to write *(\*byte)* + +nBytes + Number of bytes to write *(byte)*. Must be between 1 + and 31 (Wire library limitation) but is not checked by the library. + +.. _returns-4: + +Returns +^^^^^^^ + +I2C status *(byte)*. Returns zero if successful. + +.. _example-4: + +Example +^^^^^^^ + +.. code:: cpp + + //write 1, 2, ..., 8 to the first eight DS3232 SRAM locations + byte buf[8] = {1, 2, 3, 4, 5, 6, 7, 8}; + RTC.sramWrite(0x14, buf, 8); + +writeRTC(byte addr, byte value) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _description-7: + +Description +^^^^^^^^^^^ + +Write a single byte to RTC memory. + +.. _syntax-5: + +Syntax +^^^^^^ + +``RTC.writeRTC(addr, value);`` + +.. _parameters-5: + +Parameters +^^^^^^^^^^ + +addr + SRAM address to write *(byte)*. The valid address range is + 0x00-0x12 for DS3231, 0x00-0xFF for DS3232. The general-purpose SRAM for + the DS3232 begins at address 0x14. Address is not checked for validity + by the library. + +value + Value to write *(byte)* + +.. _returns-5: + +Returns +^^^^^^^ + +I2C status *(byte)*. Returns zero if successful. + +.. _example-5: + +Example +^^^^^^^ + +.. code:: cpp + + RTC.writeRTC(3, 14); //write the value 14 to SRAM address 3 + +readRTC(byte addr, byte \*values, byte nBytes) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _description-8: + +Description +^^^^^^^^^^^ + +Read one or more bytes from RTC RAM. + +.. _syntax-6: + +Syntax +^^^^^^ + +``RTC.readRTC(addr, values, nbytes);`` + +.. _parameters-6: + +Parameters +^^^^^^^^^^ + +addr + First SRAM address to read *(byte)*. The valid address range + is 0x00-0x12 for DS3231, 0x00-0xFF for DS3232. The general-purpose SRAM + for the DS3232 begins at address 0x14. Address is not checked for + validity by the library. + +values + An array to receive the values read *(\*byte)* + +nBytes + Number of bytes to read *(byte)*. Must be between 1 + and 32 (Wire library limitation) but is not checked by the library. + +.. _returns-6: + +Returns +^^^^^^^ + +I2C status *(byte)*. Returns zero if successful. + +.. _example-6: + +Example +^^^^^^^ + +.. code:: cpp + + //read the last eight locations of SRAM into buf + byte buf[8]; + RTC.sramRead(248, buf, 8); + +readRTC(byte addr) +~~~~~~~~~~~~~~~~~~ + +.. _description-9: + +Description +^^^^^^^^^^^ + +Reads a single byte from RTC RAM. + +.. _syntax-7: + +Syntax +^^^^^^ + +``RTC.readRTC(addr);`` + +.. _parameters-7: + +Parameters +^^^^^^^^^^ + +addr + SRAM address to read *(byte)*. The valid address range is + 0x00-0x12 for DS3231, 0x00-0xFF for DS3232. The general-purpose SRAM for + the DS3232 begins at address 0x14. Address is not checked for validity + by the library. + +.. _returns-7: + +Returns +^^^^^^^ + +Value read from the RTC *(byte)* + +.. _example-7: + +Example +^^^^^^^ + +.. code:: cpp + + byte val; + val = RTC.readRTC(3); //read the value from SRAM location 3 + +Alarm methods +------------- + +The DS3232 and DS3231 have two alarms. Alarm1 can be set to seconds +precision; Alarm2 can only be set to minutes precision. + +setAlarm(ALARM_TYPES_t alarmType, byte seconds, byte minutes, byte hours, byte daydate) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _description-10: + +Description +^^^^^^^^^^^ + +Set an alarm time. Sets the alarm registers only. To cause the INT pin +to be asserted on alarm match, use alarmInterrupt(). This method can set +either Alarm 1 or Alarm 2, depending on the value of alarmType (use the +ALARM_TYPES_t enumeration above). When setting Alarm 2, the seconds +value must be supplied but is ignored, recommend using zero. (Alarm 2 +has no seconds register.) + +.. _syntax-8: + +Syntax +^^^^^^ + +``RTC.setAlarm(alarmType, seconds, minutes, hours, dayOrDate);`` + +.. _parameters-8: + +Parameters +^^^^^^^^^^ + +alarmType + A value from the ALARM_TYPES_t enumeration, above. *(ALARM_TYPES_t)* + +seconds + The seconds value to set the alarm to. *(byte)* + +minutes + The minutes value to set the alarm to. *(byte)* + +hours + The hours value to set the alarm to. *(byte)* + +dayOrDate + The day of the week or the date of the month. For day + of the week, use a value from the Time library timeDayOfWeek_t + enumeration, i.e. dowSunday, dowMonday, dowTuesday, dowWednesday, + dowThursday, dowFriday, dowSaturday. *(byte)* + +.. _returns-8: + +Returns +^^^^^^^ + +None. + +.. _example-8: + +Example +^^^^^^^ + +.. code:: cpp + + //Set Alarm1 for 12:34:56 on Sunday + RTC.setAlarm(ALM1_MATCH_DAY, 56, 34, 12, dowSunday); + +setAlarm(ALARM_TYPES_t alarmType, byte minutes, byte hours, byte daydate) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _description-11: + +Description +^^^^^^^^^^^ + +Set an alarm time. Sets the alarm registers only. To cause the INT pin +to be asserted on alarm match, use alarmInterrupt(). This method can set +either Alarm 1 or Alarm 2, depending on the value of alarmType (use the +ALARM_TYPES_t enumeration above). However, when using this method to set +Alarm 1, the seconds value is set to zero. (Alarm 2 has no seconds +register.) + +.. _syntax-9: + +Syntax +^^^^^^ + +``RTC.setAlarm(alarmType, minutes, hours, dayOrDate);`` + +.. _parameters-9: + +Parameters +^^^^^^^^^^ + +alarmType + A value from the ALARM_TYPES_t enumeration, above. *(ALARM_TYPES_t)* + +minutes + The minutes value to set the alarm to. *(byte)* + +hours + The hours value to set the alarm to. *(byte)* + +dayOrDate + The day of the week or the date of the month. For day + of the week, use a value from the Time library timeDayOfWeek_t + enumeration, i.e. dowSunday, dowMonday, dowTuesday, dowWednesday, + dowThursday, dowFriday, dowSaturday. *(byte)* + +.. _returns-9: + +Returns +^^^^^^^ + +None. + +.. _example-9: + +Example +^^^^^^^ + +.. code:: cpp + + //Set Alarm2 for 12:34 on the 4th day of the month + RTC.setAlarm(ALM1_MATCH_DATE, 34, 12, 4); + +alarmInterrupt(byte alarmNumber, boolean alarmEnabled) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _description-12: + +Description +^^^^^^^^^^^ + +Enable or disable an alarm “interrupt”. Note that this “interrupt” +causes the RTC’s INT pin to be asserted. To use this signal as an actual +interrupt to a microcontroller, it will need to be connected properly +and programmed in the application firmware. on the RTC. + +.. _syntax-10: + +Syntax +^^^^^^ + +``RTC.alarmInterrupt(alarmNumber, enable);`` + +.. _parameters-10: + +Parameters +^^^^^^^^^^ + +alarmNumber + The number of the alarm to enable or disable, ALARM_1 or ALARM_2 *(byte)* + +alarmEnabled + true or false *(boolean)* + +.. _returns-10: + +Returns +^^^^^^^ + +None. + +.. _example-10: + +Example +^^^^^^^ + +.. code:: cpp + + RTC.alarmInterrupt(ALARM_1, true); //assert the INT pin when Alarm1 occurs. + RTC.alarmInterrupt(ALARM_2, false); //disable Alarm2 + +alarm(byte alarmNumber) +~~~~~~~~~~~~~~~~~~~~~~~ + +.. _description-13: + +Description +^^^^^^^^^^^ + +Tests whether an alarm has been triggered. If the alarm was triggered, +returns true and resets the alarm flag in the RTC, else returns false. + +.. _syntax-11: + +Syntax +^^^^^^ + +``RTC.alarm(alarmNumber);`` + +.. _parameters-11: + +Parameters +^^^^^^^^^^ + +alarmNumber + The number of the alarm to test, ALARM_1 or ALARM_2 *(byte)* + +.. _returns-11: + +Returns +^^^^^^^ + +Description *(type)* + +.. _example-11: + +Example +^^^^^^^ + +.. code:: cpp + + if ( RTC.alarm(ALARM_1) ) { //has Alarm1 triggered? + //yes, act on the alarm + } + else { + //no alarm + } + +Other methods +------------- + +temperature(void) +~~~~~~~~~~~~~~~~~ + +.. _description-14: + +Description +^^^^^^^^^^^ + +Returns the RTC temperature. + +.. _syntax-12: + +Syntax +^^^^^^ + +``RTC.temperature();`` + +.. _parameters-12: + +Parameters +^^^^^^^^^^ + +None. + +.. _returns-12: + +Returns +^^^^^^^ + +RTC temperature as degrees Celsius times four. *(int)* + +.. _example-12: + +Example +^^^^^^^ + +.. code:: cpp + + int t = RTC.temperature(); + float celsius = t / 4.0; + float fahrenheit = celsius * 9.0 / 5.0 + 32.0; + +squareWave(SQWAVE_FREQS_t freq) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _description-15: + +Description +^^^^^^^^^^^ + +Enables or disables the square wave output. + +.. _syntax-13: + +Syntax +^^^^^^ + +``RTC.squareWave(freq);`` + +.. _parameters-13: + +Parameters +^^^^^^^^^^ + +freq + a value from the SQWAVE_FREQS_t enumeration above. *(SQWAVE_FREQS_t)* + +.. _returns-13: + +Returns +^^^^^^^ + +None. + +.. _example-13: + +Example +^^^^^^^ + +.. code:: cpp + + RTC.squareWave(SQWAVE_1_HZ); //1 Hz square wave + RTC.squareWave(SQWAVE_NONE); //no square wave + +oscStopped(bool clearOSF) +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _description-16: + +Description +^^^^^^^^^^^ + +Returns the value of the oscillator stop flag (OSF) bit in the +control/status register which indicates that the oscillator is or was +stopped, and that the timekeeping data may be invalid. Optionally clears +the OSF bit depending on the argument passed. If the ``clearOSF`` +argument is omitted, the OSF bit is cleared by default. Calls to +``set()`` and ``write()`` also clear the OSF bit. + +.. _syntax-14: + +Syntax +^^^^^^ + +``RTC.oscStopped(clearOSF);`` + +.. _parameters-14: + +Parameters +^^^^^^^^^^ + +clearOSF + an optional true or false value to indicate whether the + OSF bit should be cleared (reset). If not supplied, a default value of + true is used, resetting the OSF bit. *(bool)* + +.. _returns-14: + +Returns +^^^^^^^ + +True or false *(bool)* + +.. _example-14: + +Example +^^^^^^^ + +.. code:: cpp + + if ( RTC.oscStopped(false) ) { //check the oscillator + //may be trouble + } + else { + //all is well + } diff --git a/Sming/Libraries/HMC5883L/README.md b/Sming/Libraries/HMC5883L/README.md new file mode 100644 index 0000000000..41c97d0bf1 --- /dev/null +++ b/Sming/Libraries/HMC5883L/README.md @@ -0,0 +1,3 @@ +# HMC5883L + +https://github.com/jrowberg/i2cdevlib.git diff --git a/Sming/Libraries/I2Cdev/README.md b/Sming/Libraries/I2Cdev/README.md new file mode 100644 index 0000000000..3b4850982f --- /dev/null +++ b/Sming/Libraries/I2Cdev/README.md @@ -0,0 +1,3 @@ +# I2Cdev + +https://github.com/jrowberg/i2cdevlib.git diff --git a/Sming/Libraries/LiquidCrystal/I2CLCDextraIO_assemblyProject_small.jpg b/Sming/Libraries/LiquidCrystal/I2CLCDextraIO_assemblyProject_small.jpg new file mode 100644 index 0000000000..1d77ded58b Binary files /dev/null and b/Sming/Libraries/LiquidCrystal/I2CLCDextraIO_assemblyProject_small.jpg differ diff --git a/Sming/Libraries/LiquidCrystal/README.md b/Sming/Libraries/LiquidCrystal/README.md new file mode 100644 index 0000000000..ee49ffd811 --- /dev/null +++ b/Sming/Libraries/LiquidCrystal/README.md @@ -0,0 +1,48 @@ +# LiquidCrystal + +## Introduction ## + +![LCD library](I2CLCDextraIO_assemblyProject_small.jpg) + +Welcome to the *LCD Library* for **Arduino** and **Chipkit**. It is a derivate of the original LiquidCrystal Library as sourced in the Arduino SDK. It has been developed to be compatible with the current LiquidCrystal library, +its performance is almost 5 times faster and fully extendable if need be. + +It supports most ``Hitachi HD44780`` based LCDs, or compatible, connected to any project using: 4, 8 +wire parallel interface, I2C IO port expander (native I2C and bit bang) and Shift Regiter. + +It currently supports 4 types of connections: + +* 4 bit parallel LCD interface +* 8 bit parallel LCD interface +* I2C IO bus expansion board with the PCF8574* I2C IO expander ASIC such as [I2C LCD extra IO](http://www.electrofunltd.com/2011/10/i2c-lcd-extra-io.html "I2C LCD extra IO"). +* ShiftRegister adaptor board as described [Shift Register project home](http://code.google.com/p/arduinoshiftreglcd/ "Shift Register project home") or in the HW configuration described below, 2 and 3 wire configurations supported. +* ShiftRegister 3 wire latch adaptor board as described [ShiftRegister 3 Wire Home](http://www.arduino.cc/playground/Code/LCD3wires "ShiftRegister 3 Wire Home") +* Support for 1 wire shift register [ShiftRegister 1 Wire](http://www.romanblack.com/shift1.htm "ShiftRegister 1 Wire") +* I2C bus expansion using general purpose IO lines. + +### How do I get set up? ### + +* Please refer to the project's [wiki](https://bitbucket.org/fmalpartida/new-liquidcrystal/wiki/Home "wiki") + + +### Contributors +The library has had the invaluable contribution of: + +* [piccaso](http://www.3guys1laser.com/blog-cheap-arduino-2-wire-lcd-display-0 "picas") - Florian Fida - Flo, thanks for testing and improving the SR library, initial version of the 1 wire interface and speed improvements. +* B. Perry - *bperrybap@opensource.billsworld.billandterrie.com*, with his thoughtful contribution, speed improvements and development support for the SR2W library. +* Adrian Piccioli, with his contribution to the i2c GPIO support. +* [todbot](https://github.com/todbot "todbot") Tod E. Kurt for the [softwarei2cmaster](https://github.com/todbot/SoftI2CMaster "softwarei2cmaster") library. +* [felias-fogg](https://github.com/felias-fogg) - Bernhard for the [softwarei2cmaster fast](https://github.com/felias-fogg/SoftI2CMaster "softwirei2cmaster") + +#### Contribution guidelines + +* Writing tests +* Code review +* Help out with bug fixing +* Setup a project logo +* Write new drivers to support more LCDs. + +### Who do I talk to? ### + +* Repo owner or admin +* For SoftI2CMaster latest versions, updates and support, please refer to [SoftI2CMaster](https://github.com/todbot/SoftI2CMaster "todbot") diff --git a/Sming/Libraries/MCP23017/README.md b/Sming/Libraries/MCP23017/README.md new file mode 100644 index 0000000000..c8044f4733 --- /dev/null +++ b/Sming/Libraries/MCP23017/README.md @@ -0,0 +1,19 @@ +# MCP23017 + +https://github.com/adafruit/Adafruit-MCP23017-Arduino-Library.git + +This is a library for the MCP23017 I2c Port Expander + +These chips use I2C to communicate, 2 pins required to interface + +Adafruit invests time and resources providing this open source code, +please support Adafruit and open-source hardware by purchasing +products from Adafruit! + +Written by Limor Fried/Ladyada for Adafruit Industries. +BSD license, check license.txt for more information +All text above must be included in any redistribution + +To download. click the DOWNLOADS button in the top right corner, rename the uncompressed folder Adafruit_MCP23017. Check that the Adafruit_MCP23017 folder contains Adafruit_MCP23017.cpp and Adafruit_MCP23017.h + +Place the Adafruit_MCP23017 library folder your /libraries/ folder. You may need to create the libraries subfolder if its your first library. Restart the IDE. diff --git a/Sming/Libraries/MCP23S17/README.md b/Sming/Libraries/MCP23S17/README.md new file mode 100644 index 0000000000..ecf85c0416 --- /dev/null +++ b/Sming/Libraries/MCP23S17/README.md @@ -0,0 +1,342 @@ +MCP23S17 +======== + +https://github.com/n0mjs710/MCP23S17.git + +Arduino Driver for Microchip MCP23S17 + +MCP23S17 Class for Arduino + +Introduction: + +This class is written to simplify using the Microchip MCP23S17 general purpose I/O expander IC in the Arduino environment. Some understanding of the MCP23S17 is required, so if you are not familiar with it, download the datasheet for it and have a look. The rest of this description will assume a *basic* understanding of the chip. + +Implementation: + +The goal of this implementation is to provide a software interface that mimics the existing Arduino I/O functions: + + * pinMode(pin, mode) + * digitalWrite(pin, value) + * digitalRead(pin) + +The class does include several more methods that can be used to simplify configuration in the same "Arduino-ish" way, methods for writing/reading 8-bit registers (configuration and I/O ports) at once, as well as writing/reading consecutive registers (allowing all 16 bits to be read or written with one method call). The interrupt features of the chip are not directly supported with method for specifically configuring them, however, the byte and word read/write methods may be used to configure and use the interrupt features. These features can get somewhat complicated, and any user prepared to use them will likely prefer the more generic methods for controlling them. + +Upon initialization of an MCP23S17 as an object, ALL MCP23S17s on the SPI bus (sharing the same slave select) will be placed into hardware addressing mode. This allows up to 8 MCP23S17s to be used with a single slave select. + +***Methods:*** + +**MCP()** + +Description + +Instantiate an MCP23S17 device as an object. + +Syntax + + MCP object_name(address, slave_select) + +Parameters + + object_name: any arbitrary name given to create the object + + address: address (0-7) of the device configured with address (pins A0, A1, A2) + + slave_select: a valid *Arduino* pin number. + +Returns + + none + +Example + + MCP onechip(1, 10); // create an object at address 1 called "onechip", using pin 10 as slave select + MCP twochip(2, 10); // create an object at address 2 called "twochip", using pin 10 as slave select + + +**pinMode()** + +Description + +Configure pin(s) as either input or output on the selected object (device specified by an address) + +Syntax + + object.name.pinMode(pin, mode); + or + object.name.pinMode(mode); + +Parameters + + object_name: the name given when this object was created + + pin: the pin number (1-16) on which to set as input or output + + mode: if a pin is specified, either a "HIGH" (1) for input (default) or a "LOW" (0) for output. If a pin is not specified, mode should be a word indicating the mode of each of the 16 I/O pins on the chip. + +Returns + + none + +Example + + void setup() { + onechip.pinMode(4, HIGH); // sets pin 4 as an input + onechip.pinMode(16, LOW); // sets pin 16 as an output + twochip.pinMode(0B0000111100001111); // sets pins 1-4 and 9-12 as input, 5-8 and 13-16 as output + } + + + +**pullupMode()** + +Description + +Configure the weak pull-up resistors on pins defined as inputs + +This has no effect on pins that are configured as outputs. + +Syntax + + object_name.pullupMode(pin, mode); + or + object_name.pullupMode(mode); + +Parameters + + object_name: the name given when this object was created + + pin: the pin number (1-16) on which to enable or disable the internal weak pull-up resistor + + mode: if a pin is specified, either "HIGH" (1) to enable or "LOW" (0) to disable (default) the weak pull-up resistor on the specified pin. If a pin is not specified, mode should be a word indicating the pull-up mode of each of the 16 pins on the chip. Configuring pull-up has no effect on pins while they are configured as output. + +Returns + + none + +Example + + void setup() { + onechip.pullupMode(4, HIGH); // enable the pull-up on pin 4 + twochip.pullupMode(0B0000111100000000); // enable the pull-ups on pins 9-12 + } + + + +**inputInvert()** + +Description + +Configure inversion on pins configured as inputs. + +This will cause an inverted input pin to read as "LOW" (0) when it is actually in a high state, or as "HIGH" (1) when it is actually in a low state. This has no effect on pins that are configured as outputs. + +Syntax + + object_name.inputInvert(pin, inversion); + or + object_name.inputInvert(inversion); + +Parameters + + object_name: the name given when this object was created + + pin: the pin number (1-16) on which to set or clear inversion + + inversion: if a pin is specified, either "HIGH" (1) is specified to enable, or "LOW" (0) to disable (default) inversion on the specified pin. If a pin is not specified, mode should be a word indicating the inversion state of each of the 16 pins on the chip. Configuring inversion has no effect on pins while they are configured as output. + +Returns + + none + +Example + + void setup() { + onechip.inputInvert(4, LOW); // disable inversion on pin 4 + twochip.inputInvert(0B0000000000001111); // enable inversion on pins 1-4 + } + + +**digitalWrite()** + +Description + +Write a "HIGH" or "LOW" value to a digital I/O pin(s) + +Syntax + + object_name.digitalWrite(pin, value); + or + object_name.digitalWrite(value); + +Parameters + + object_name: the name given when this object was created + + pin: the pin number (1-16) who's value will be set + + value: if a pin is specified, either a "HIGH" (1) or a "LOW" (0) value may be set on the specified pin. If a pin is not specified, value should be a word indicating the output state of all 16 pins on the device. Writing pins configured as inputs has no effect. + +Returns + + none + +Example + + void loop() { + onechip.digitalWrite(16, HIGH); // set pin 16 to "HIGH" + twochip.digitalWrite(0B1100000000110000); // Set 5, 6, 15 & 16 to high, 7,8, 13 & 14 to low - inputs ignored + } + + +**digitalRead()** + +Description + +Reads the value of input pin(s), either "HIGH" ("1") or "LOW" ("0) + +Syntax + + object_name.digitalRead(pin); + or + object_name.digitalRead(); + +Parameters + + object_name: the name given when this object was created + + pin: the pin number (1-16) who's value will be read. If no pin number is supplied, a word will be read containing the input state of all pins. The values for pins configured as output should be disregarded if the "word-mode" version is used. + +Returns + + "HIGH" (1) or "LOW" (0) if a pin is supplied. a word (16 bits) is returned if no pin argument is given + +Example + + void loop() { + int onevalue; + int twovalue; + + onevalue = onechip.digitalRead(4); // assigns the value of pin4 to onevalue + twovalue = twochip.digitalRead(); // assigns the value of all 16 I/O pins to twovalue + } + + +**wordWrite()** + +Description: + +This is an advanced method to write a register pair in the MCP23S17. This class operates the MCP23S17 in "BANK=0" mode. The intention is that a registers for both ports may be written by supplying a single word as an argument. The low byte is written to the register address supplied, and the high byte to the next higher register address. + +Syntax" + + object_name.wordWrite(base register, value); + +Parameters: + + object_name: the name given when this object was created + + base register: the beginning register address to write, for example, if 0x02 is given, the low byte of "value" will be written to 0x02 and the high byte of "value" to the register at 0x03 + + value: a word (unsigned int) that will be broken into two bytes and written to two consecutive registers, starting with the "base register" address + +Returns: + + none + +Example + + void loop() { + onechip.wordWrite(0x12, 0xFF00); // Set GPIOA to 0x00 and GPIOB to OxFF + } + +**byteWrite()** + +Description: + +This is an advanced method to write any single register in the MCP23S17. + +Syntax: + + object_name.byteWrite(register, value); + +Parameters: + + object_name: the name given when this object was created + +register: the register address to write + + value: a byte (unsigned char) that will be written to the specified registers + +Returns: + + none + +Example: + + void loop() { + twochip.byteWrite(0x13, 0xF0); // Set GPIOB (portB) to 0xF0 (0B11110000) + } + + +**byteRead()** + +Description: + +This is an advanced method to read any single register in the MCP23S17. + +Syntax: + + object_name.byteRead(register); + +Parameters: + + object_name: the name given when this object was created + + register: the register address to be read + +Returns: + + unsigned char (uint8_t) + +Example: + + void loop() { + int twovalue; + twovalue = twochip.byteRead(0x12); // Read GPIOA (portA) + } + + + +Full Example: + + MCP onechip(1, 10); // create an object at address 1 called "onechip", using pin 10 as slave select + MCP twochip(2, 10); // create an object at address 2 called "twochip", using pin 10 as slave select + + void setup() { + onechip.pinMode(4, HIGH); // sets pin 4 as an input + onechip.pinMode(16, LOW); // sets pin 16 as an output + twochip.pinMode(0B0000111100001111); // sets pins 1-4 and 9-12 as input, 5-8 and 13-16 as output + + onechip.pullupMode(4, HIGH); // enable the pull-up on pin 4 + twochip.pullupMode(0B0000111100000000); // enable the pull-ups on pins 9-1 + + onechip.inputInvert(4, LOW); // disable inversion on pin 4 + twochip.inputInvert(0B0000000000001111); // enable inversion on pins 1-4 + } + + void loop() { + int onevalue; + int twovalue; + + onechip.digitalWrite(16, HIGH); // set pin 16 to "HIGH" + twochip.digitalWrite(0B1100000000110000); // Set 5, 6, 15 & 16 to high, 7,8, 13 & 14 to low - inputs ignored + + onevalue = onechip.digitalRead(4); // assigns the value of pin4 to onevalue + twovalue = twochip.digitalRead(); // assigns the value of all 16 I/O pins to twovalue + + /* These are for context only - use them only if you really know what you're doing + onechip.wordWrite(0x12, 0xFF00); // Set GPIOA to 0x00 and GPIOB to OxFF + twochip.byteWrite(0x13, 0xF0); // Set GPIOB (portB) to 0xF0 (0B11110000) + twovalue = twochip.byteRead(0x12); // Read GPIOA (portA) + */ + } diff --git a/Sming/Libraries/MFRC522/README.rst b/Sming/Libraries/MFRC522/README.rst new file mode 100644 index 0000000000..cc3913ccc8 --- /dev/null +++ b/Sming/Libraries/MFRC522/README.rst @@ -0,0 +1,384 @@ +MFRC522 +======= + +.. note:: + This is a copy of the readme from 12/6/19, however the code in this library was last updated 23/3/2017. + + https://github.com/miguelbalboa/rfid.git + +Arduino library for MFRC522 and other RFID RC522 based modules. + +Read and write different types of Radio-Frequency IDentification (RFID) cards +on your Arduino using a RC522 based reader connected via the Serial Peripheral +Interface (SPI) interface. + + +.. _development: + +Development +----------- + +**The development by owner miguelbalboa has ended**. + +**Feature status: complete freeze**; no function or API change + +**Code status: paritial freeze**; just fixes/typos or documentation updates; *no* extentions for other boards; *no* new examples + +**Maintenance status: sporadically** + +**Why no further development?** +This library has a long history and is used in many projects. This projects often do not document what version they use. Commiting changes maybe brake those old project and lead to bad experience (for beginners) and support request. For those reasons the library is in freeze mode. You can still commit typo, documentation or bug fixes. + + +.. _before buy: + +Before buy +---------- +Please notice that there are many sellers (ebay, aliexpress, ..) who sell mfrc522 boards. **The quality of these boards are extremely different.** Some are soldered with wrong/low quality capacitors or fake/defect mfrc522. + +**Please consider buying several devices from different suppliers.** So the chance of getting a working device is higher. + +If you got a bad board and you can tell us how to detect those boards (silk, chip description, ..), please share your knowledge. + + +.. _what works and not: + +What works and not? +------------------- + +* **Works** + + #. Communication (Crypto1) with MIFARE Classic (1k, 4k, Mini). + #. Communication (Crypto1) with MIFARE Classic compatible PICCs. + #. Firmware self check of MFRC522. + #. Set the UID, write to sector 0, and unbrick Chinese UID changeable MIFARE cards. + #. Manage the SPI chip select pin (aka SS, SDA) + +* **Works partially** + + #. Communication with MIFARE Ultralight. + #. Other PICCs (Ntag216). + #. More than 2 modules, require a multiplexer `#191 `_. + +* **Doesn't work** + + #. MIFARE DESFire, MIFARE DESFire EV1/EV2, not supported by software. + #. Communication with 3DES or AES, not supported by software. + #. Peer-to-peer (ISO/IEC 18092), not `supported by hardware`_. + #. Communication with smart phone, not `supported by hardware`_. + #. Card emulation, not `supported by hardware`_. + #. Use of IRQ pin. But there is a proof-of-concept example. + #. With Arduino Yun see `#111 `_, not supported by software. + #. With Intel Galileo (Gen2) see `#310 `__, not supported by software. + #. Power reduction modes `#269 `_, not supported by software. + #. I2C instead of SPI `#240 `_, not supported by software. + #. UART instead of SPI `#281 `_, not supported by software. + +* **Need more?** + + #. If software: code it and make a pull request. + #. If hardware: buy a more expensive like PN532 (supports NFC and many more, but costs about $15 and not usable with this library). + + +.. _compatible ide: + +Compatible IDE +-------------- +This library works with Arduino IDE 1.6, older versions are **not supported** and will cause compiler errors. The built-in library manager is supported. + +If you use your own compiler, you have to enable ``c++11``-support. + + +.. _compatible boards: + +Compatible boards +----------------- + +**!!!Only for advanced users!!!** + +This library is compatible with the Teensy and ESP8266 if you use the board plugin of the Arduino IDE. Not all examples are available for every board. You also have to change pins. See `pin layout`_. + +Some user made some patches/suggestions/ports for other boards: + +* Linux: https://github.com/miguelbalboa/rfid/pull/216 +* chipKIT: https://github.com/miguelbalboa/rfid/pull/230 +* ESP8266 (native): https://github.com/miguelbalboa/rfid/pull/235 +* LPCOPen (in C): https://github.com/miguelbalboa/rfid/pull/258 + +Note that the main target/support of library is still Arduino. + +.. _support issue: + +Support/issue +------------- +1. First checkout `what works and not`_ and `troubleshooting`_ . + +2. It seems to be a hardware issue or you need support to program your project? + Please ask in the official `Arduino forum`_, where you would get a much faster answer than on Github. + +3. It seems to be a software issue? + Open an issue on Github. + + +.. _code style: + +Code style +---------- + +Please use ``fixed integers``, see `stdint.h`_. Why? This library is compatible with different boards which use different architectures (16bit and 32bit.) Unfixed ``int`` variables have different sizes in different environments and may cause unpredictable behaviour. + + +.. _pin layout: + +Pin Layout +---------- + +The following table shows the typical pin layout used: + ++--------------+----------+-------------+---------+---------+------------------+-----------+-----+--------+-----+ +| | PCD | Arduino | Teensy | | | | | | | +| | | | | | | | | | | +| | MFRC522 | Uno / 101 | Mega | Nano v3 | Leonardo / Micro | Pro Micro | 2.0 | ++ 2.0 | 3.1 | ++--------------+----------+-------------+---------+---------+------------------+-----------+-----+--------+-----+ +| Signal | Pin | Pin | Pin | Pin | Pin | Pin | Pin | Pin | Pin | ++==============+==========+=============+=========+=========+==================+===========+=====+========+=====+ +| RST/Reset | RST | 9 [1]_ | 5 [1]_ | D9 | RESET / ICSP-5 | RST | 7 | 4 | 9 | ++--------------+----------+-------------+---------+---------+------------------+-----------+-----+--------+-----+ +| SPI SS | SDA [3]_ | 10 [2]_ | 53 [2]_ | D10 | 10 | 10 | 0 | 20 | 10 | ++--------------+----------+-------------+---------+---------+------------------+-----------+-----+--------+-----+ +| SPI MOSI | MOSI | 11 / ICSP-4 | 51 | D11 | ICSP-4 | 16 | 2 | 22 | 11 | ++--------------+----------+-------------+---------+---------+------------------+-----------+-----+--------+-----+ +| SPI MISO | MISO | 12 / ICSP-1 | 50 | D12 | ICSP-1 | 14 | 3 | 23 | 12 | ++--------------+----------+-------------+---------+---------+------------------+-----------+-----+--------+-----+ +| SPI SCK | SCK | 13 / ICSP-3 | 52 | D13 | ICSP-3 | 15 | 1 | 21 | 13 | ++--------------+----------+-------------+---------+---------+------------------+-----------+-----+--------+-----+ + ++--------------+---------------+ +| | ESP8266 | +| | | +| | Wemos D1 mini | ++--------------+---------------+ +| Signal | Pin | ++==============+===============+ +| RST/Reset | D3 | ++--------------+---------------+ +| SPI SS | D8 | ++--------------+---------------+ +| SPI MOSI | D7 | ++--------------+---------------+ +| SPI MISO | D6 | ++--------------+---------------+ +| SPI SCK | D5 | ++--------------+---------------+ + +.. [1] Configurable, typically defined as RST_PIN in sketch/program. +.. [2] Configurable, typically defined as SS_PIN in sketch/program. +.. [3] The SDA pin might be labeled SS on some/older MFRC522 boards. + + +.. _hardware: + +Hardware +-------- + +There are three hardware components involved: + +1. **Micro Controller**: + +* An `Arduino`_ or compatible executing the Sketch using this library. + +* Prices vary from USD 7 for clones, to USD 75 for "starter kits" (which + might be a good choice if this is your first exposure to Arduino; + check if such kit already includes the Arduino, Reader, and some Tags). + +2. **Proximity Coupling Device (PCD)**: + +* The PCD is the actual RFID **Reader** based on the `NXP MFRC522`_ Contactless + Reader Integrated Circuit. + +* Readers can be found on `eBay`_ for around USD 5: search for *"rc522"*. + +* You can also find them on several web stores. They are often included in + *"starter kits"*, so check your favourite electronics provider as well. + +3. **Proximity Integrated Circuit Card (PICC)**: + +* The PICC is the RFID **Card** or **Tag** using the `ISO/IEC 14443A`_ + interface, for example Mifare or NTAG203. + +* One or two might be included with the Reader or *"starter kit"* already. + + +.. _protocol: + +Protocols +--------- + +1. The micro controller and the reader use SPI for communication. + +* The protocol is described in the `NXP MFRC522`_ datasheet. + +* See the `Pin Layout`_ section for details on connecting the pins. + +2. The reader and the tags communicate using a 13.56 MHz electromagnetic field. + +* The protocol is defined in ISO/IEC 14443-3:2011 Part 3 Type A. + + * Details are found in chapter 6 *"Type A – Initialization and anticollision"*. + + * See http://wg8.de/wg8n1496_17n3613_Ballot_FCD14443-3.pdf for a free version + of the final draft (which might be outdated in some areas). + + * The reader does not support ISO/IEC 14443-3 Type B. + + +.. _security: + +Security +-------- + +* The **UID** of a card **can not be used** as an unique identification for security related projects. Some Chinese cards allow to change the UID which means you can easily clone a card. For projects like *access control*, *door opener* or *payment systems* you **must implement** an **additional security mechanism** like a password or normal key. + +* This library only supports crypto1-encrypted communication. Crypto1 has been known as `broken`_ for a few years, so it does NOT offer ANY security, it is virtually unencrypted communication. **Do not use it for any security related applications!** + +* This library does not offer 3DES or AES authentication used by cards like the Mifare DESFire, it may be possible to be implemented because the datasheet says there is support. We hope for pull requests :). + + +.. _troubleshooting: + +Troubleshooting +--------------- + +* **I don't get input from reader** or **WARNING: Communication failure, is the MFRC522 properly connected?** + + #. Check your physical connection, see `Pin Layout`_ . + #. Check your pin settings/variables in the code, see `Pin Layout`_ . + #. Check your pin header soldering. Maybe you have cold solder joints. + #. Check voltage. Most breakouts work with 3.3V. + #. SPI only works with 3.3V, most breakouts seem 5V tollerant, but try a level shifter. + #. SPI does not like long connections. Try shorter connections. + #. SPI does not like prototyping boards. Try soldered connections. + #. According to reports #101, #126 and #131, there may be a problem with the soldering on the MFRC522 breakout. You could fix this on your own. + + +* **Firmware Version: 0x12 = (unknown) or other random values** + + #. The exact reason of this behaviour is unknown. + #. Some boards need more time after `PCD_Init()` to be ready. As workaround add a `delay(4)` directly after `PCD_Init()` to give the PCD more time. + #. If this sometimes appears, a bad connection or power source is the reason. + #. If the firmware version is reported permanent, it is very likely that the hardware is a fake or has a defect. Contact your supplier. + + +* **Sometimes I get timeouts** or **sometimes tag/card does not work.** + + #. Try the other side of the antenna. + #. Try to decrease the distance between the MFRC522 and your tag. + #. Increase the antenna gain per firmware: ``mfrc522.PCD_SetAntennaGain(mfrc522.RxGain_max);`` + #. Use better power supply. + #. Hardware may be corrupted, most products are from china and sometimes the quality is really poor. Contact your seller. + + +* **My tag/card doesn't work.** + + #. Distance between antenna and token too large (>1cm). + #. You got the wrong type PICC. Is it really 13.56 MHz? Is it really a Mifare Type A? + #. NFC tokens are not supported. Some may work. + #. Animal RFID tags are not supported. They use a different frequency (125 kHz). + #. Hardware may be corrupted, most products are from china and sometimes the quality is really poor. Contact your seller. + #. Newer versions of Mifare cards like DESFire/Ultralight maybe not work according to missing authentication, see `security`_ or different `protocol`_. + #. Some boards bought from Chinese manufactures do not use the best components and this can affect the detection of different types of tag/card. In some of these boards, the L1 and L2 inductors do not have a high enough current so the signal generated is not enough to get Ultralight C and NTAG203 tags to work, replacing those with same inductance (2.2uH) but higher operating current inductors should make things work smoothly. Also, in some of those boards the harmonic and matching circuit needs to be tuned, for this replace C4 and C5 with 33pf capacitors and you are all set. (Source: `Mikro Elektronika`_) + +* **My mobile phone doesn't recognize the MFRC522** or **my MFRC522 can't read data from other MFRC522** + + #. Card simulation is not supported. + #. Communication with mobile phones is not supported. + #. Peer to peer communication is not supported. + +* **I can only read the card UID.** + + #. Maybe the `AccessBits` have been accidentally set and now an unknown password is set. This can not be reverted. + #. Probably the card is encrypted. Especially official cards like public transport, university or library cards. There is *no* way to get access with this library. + +* **I need more features.** + + #. If software: code it and make a pull request. + #. If hardware: buy a more expensive chip like the PN532 (supports NFC and many more, but costs about $15) + + +.. _license: + +License +------- +This is free and unencumbered software released into the public domain. + +Anyone is free to copy, modify, publish, use, compile, sell, or +distribute this software, either in source code form or as a compiled +binary, for any purpose, commercial or non-commercial, and by any +means. + +In jurisdictions that recognize copyright laws, the author or authors +of this software dedicate any and all copyright interest in the +software to the public domain. We make this dedication for the benefit +of the public at large and to the detriment of our heirs and +successors. We intend this dedication to be an overt act of +relinquishment in perpetuity of all present and future rights to this +software under copyright law. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR +OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +OTHER DEALINGS IN THE SOFTWARE. + +For more information, please refer to https://unlicense.org/ + + +.. _dependency: + +Dependency +---------- + +* **Arduino.h** + + * From: Arduino IDE / target specific + * License: (target: Arduino) GNU Lesser General Public License 2.1 + +* **SPI.h** + + * From: Arduino IDE / target specific + * License: (target: Arduino) GNU Lesser General Public License 2.1 + +* **stdint.h** + + * From: Arduino IDE / Compiler and target specific + * License: different + + +History +------- + +The MFRC522 library was first created in Jan 2012 by Miguel Balboa (from +http://circuitito.com) based on code by Dr. Leong (from http://B2CQSHOP.com) +for *"Arduino RFID module Kit 13.56 Mhz with Tags SPI W and R By COOQRobot"*. + +It was translated into English and rewritten/refactored in the fall of 2013 +by Søren Thing Andersen (from http://access.thing.dk). + +It has been extended with functionality to alter sector 0 on Chinese UID changeable MIFARE card in Oct 2014 by Tom Clement (from http://tomclement.nl). + +Maintained by miguelbalboa until 2016. +Maintained by Rotzbua from 2016 until 2018. + + +.. _arduino: https://arduino.cc/ +.. _ebay: https://www.ebay.com/ +.. _iso/iec 14443a: https://en.wikipedia.org/wiki/ISO/IEC_14443 +.. _iso/iec 14443-3\:2011 part 3: +.. _nxp mfrc522: https://www.nxp.com/documents/data_sheet/MFRC522.pdf +.. _broken: https://eprint.iacr.org/2008/166 +.. _supported by hardware: https://web.archive.org/web/20151210045625/http://www.nxp.com/documents/leaflet/939775017564.pdf +.. _Arduino forum: https://forum.arduino.cc +.. _stdint.h: https://en.wikibooks.org/wiki/C_Programming/C_Reference/stdint.h +.. _Mikro Elektronika: https://forum.mikroe.com/viewtopic.php?f=147&t=64203 diff --git a/Sming/Libraries/MFRC522/UNLICENSE b/Sming/Libraries/MFRC522/UNLICENSE new file mode 100644 index 0000000000..efb9808816 --- /dev/null +++ b/Sming/Libraries/MFRC522/UNLICENSE @@ -0,0 +1,24 @@ +This is free and unencumbered software released into the public domain. + +Anyone is free to copy, modify, publish, use, compile, sell, or +distribute this software, either in source code form or as a compiled +binary, for any purpose, commercial or non-commercial, and by any +means. + +In jurisdictions that recognize copyright laws, the author or authors +of this software dedicate any and all copyright interest in the +software to the public domain. We make this dedication for the benefit +of the public at large and to the detriment of our heirs and +successors. We intend this dedication to be an overt act of +relinquishment in perpetuity of all present and future rights to this +software under copyright law. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR +OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +OTHER DEALINGS IN THE SOFTWARE. + +For more information, please refer to diff --git a/Sming/Libraries/MMA_7455/README.md b/Sming/Libraries/MMA_7455/README.md new file mode 100644 index 0000000000..79147e415a --- /dev/null +++ b/Sming/Libraries/MMA_7455/README.md @@ -0,0 +1,5 @@ +# MMA-7455 + +Library for the MMA-7455 3-axis accelerometer + +[GIT repository](https://github.com/kempermo/MMA-7455-Library.git) diff --git a/Sming/Libraries/Mirf/README.md b/Sming/Libraries/Mirf/README.md new file mode 100644 index 0000000000..7ca565464e --- /dev/null +++ b/Sming/Libraries/Mirf/README.md @@ -0,0 +1,3 @@ +# Mirf + +Arduino port of Mirf for the NRF24L01 modules diff --git a/Sming/Libraries/OneWire/README.md b/Sming/Libraries/OneWire/README.md new file mode 100644 index 0000000000..b546a61c27 --- /dev/null +++ b/Sming/Libraries/OneWire/README.md @@ -0,0 +1,3 @@ +# Arduino OneWire + +https://github.com/PaulStoffregen/OneWire.git diff --git a/Sming/Libraries/SDCard/README.md b/Sming/Libraries/SDCard/README.md new file mode 100644 index 0000000000..5cbc874c2b --- /dev/null +++ b/Sming/Libraries/SDCard/README.md @@ -0,0 +1,3 @@ +# SD Card + +Low-level support code for accessing SD Cards using FATFS. diff --git a/Sming/Libraries/SI7021/README.md b/Sming/Libraries/SI7021/README.rst similarity index 52% rename from Sming/Libraries/SI7021/README.md rename to Sming/Libraries/SI7021/README.rst index f657e9c32b..3a9b74a0f8 100644 --- a/Sming/Libraries/SI7021/README.md +++ b/Sming/Libraries/SI7021/README.rst @@ -3,6 +3,7 @@ SI7021 Arduino library for SI7020 and SI7021 environmental sensors -Example: - Humidity_SI7021 - MeteoControl_mqtt +Examples: + +* :sample:`Humidity_SI7021` +* :sample:`MeteoControl_mqtt` diff --git a/Sming/Libraries/Servo/README.md b/Sming/Libraries/Servo/README.md new file mode 100644 index 0000000000..2b6a698c3f --- /dev/null +++ b/Sming/Libraries/Servo/README.md @@ -0,0 +1,3 @@ +# Servo + +Library to control RC servos with PWM signals. diff --git a/Sming/Libraries/SparkFun_APDS9960/README.md b/Sming/Libraries/SparkFun_APDS9960/README.md new file mode 100644 index 0000000000..b5d3fb6541 --- /dev/null +++ b/Sming/Libraries/SparkFun_APDS9960/README.md @@ -0,0 +1,82 @@ +SparkFun APDS9960 RGB and Gesture Sensor Arduino Library +========================================================= + +![Avago APDS-9960 Breakout Board - SEN-12787 ](https://cdn.sparkfun.com/r/92-92/assets/parts/9/6/0/3/12787-01.jpg) + +[*Avago APDS-9960 Breakout Board (SEN-12787)*](https://www.sparkfun.com/products/12787) + +Getting Started +--------------- + +* Download the Git repository as a ZIP ("Download ZIP" button) +* Unzip +* Copy the entire library directory (APDS-9960_RGB_and_Gesture_Sensor_Arduino_Library +) to \/libraries +* Open the Arduino program +* Select File -> Examples -> SparkFun_APDS9960 -> GestureTest +* Plug in your Arduino and APDS-9960 with the following connections + +*-OR-* + +* Use the library manager + +| Arduino Pin | APDS-9960 Board | Function | +|---|---|---| +| 3.3V | VCC | Power | +| GND | GND | Ground | +| A4 | SDA | I2C Data | +| A5 | SCL | I2C Clock | +| 2 | INT | Interrupt | + +* Go to Tools -> Board and select your Arduino board +* Go to Tools -> Serial Port and select the COM port of your Arduino board +* Click "Upload" +* Go to Tools -> Serial Monitor +* Ensure the baud rate is set at 9600 baud +* Swipe your hand over the sensor in various directions! + +Repository Contents +------------------- + +* **/examples** - Example sketches for the library (.ino). Run these from the Arduino IDE. +* **/src** - Source files for the library (.cpp, .h). +* **library.properties** - General library properties for the Arduino package manager. + +Documentation +-------------- + +* **[Installing an Arduino Library Guide](https://learn.sparkfun.com/tutorials/installing-an-arduino-library)** - Basic information on how to install an Arduino library. +* **[Product Repository](https://github.com/sparkfun/APDS-9960_RGB_and_Gesture_Sensor)** - Main repository (including hardware files) for the SparkFun_APDS9960 RGB and Gesture Sensor. +* **[Hookup Guide](https://learn.sparkfun.com/tutorials/apds-9960-rgb-and-gesture-sensor-hookup-guide)** - Basic hookup guide for the sensor. + +Products that use this Library +--------------------------------- + +* [SEN-12787](https://www.sparkfun.com/products/12787)- Avago APDS-9960 + +Version History +--------------- +* [V_1.4.1](https://github.com/sparkfun/SparkFun_APDS-9960_Sensor_Arduino_Library/tree/V_1.4.1) - Removing blank files, updating library.properties file. +* [V_1.4.0](https://github.com/sparkfun/APDS-9960_RGB_and_Gesture_Sensor_Arduino_Library/tree/V_1.4.0) - Updated to new library structure +* V_1.3.0 - Implemented disableProximitySensor(). Thanks to jmg5150 for catching that! +* V_1.2.0 - Added pinMode line to GestureTest demo to fix interrupt bug with some Arduinos +* V_1.1.0 - Updated GestureTest demo to not freeze with fast swipes +* V_1.0.0: Initial release +* Ambient and RGB light sensing implemented +* Ambient light interrupts working +* Proximity sensing implemented +* Proximity interrupts working +* Gesture (UP, DOWN, LEFT, RIGHT, NEAR, FAR) sensing implemented + +License Information +------------------- + +This product is _**open source**_! + +The **code** is beerware; if you see me (or any other SparkFun employee) at the local, and you've found our code helpful, please buy us a round! + +Please use, reuse, and modify these files as you see fit. Please maintain attribution to SparkFun Electronics and release anything derivative under the same license. + +Distributed as-is; no warranty is given. + +- Your friends at SparkFun. diff --git a/Sming/Libraries/TFT_ILI9163C/README.md b/Sming/Libraries/TFT_ILI9163C/README.md index cc7c74cbce..407316937a 100644 --- a/Sming/Libraries/TFT_ILI9163C/README.md +++ b/Sming/Libraries/TFT_ILI9163C/README.md @@ -1,4 +1,4 @@ -TFT_ILI9163C +# TFT_ILI9163C ILI9163C- A fast SPI driver for TFT that use Ilitek ILI9163C. diff --git a/Sming/Libraries/Ultrasonic/README.md b/Sming/Libraries/Ultrasonic/README.md new file mode 100644 index 0000000000..915a619f7a --- /dev/null +++ b/Sming/Libraries/Ultrasonic/README.md @@ -0,0 +1,6 @@ +# Ultrasonic + +Tested on modules: + +* HC-SR04 - ranges: 2-400cm, power: 5v, levels: TTL, for work with 3.3v need voltage divider on ECHO pin +* US-100 - power: 3.3v-5v, temp. compensation diff --git a/Sming/Libraries/WS2812/README.rst b/Sming/Libraries/WS2812/README.rst new file mode 100644 index 0000000000..7b2319a53f --- /dev/null +++ b/Sming/Libraries/WS2812/README.rst @@ -0,0 +1,4 @@ +WS2812 Neopixel +=============== + +http://wp.josh.com/2014/05/13/ws2812-neopixels-are-not-so-finicky-once-you-get-to-know-them/ diff --git a/Sming/Libraries/components.mk b/Sming/Libraries/components.mk deleted file mode 100644 index aba8b774b7..0000000000 --- a/Sming/Libraries/components.mk +++ /dev/null @@ -1,6 +0,0 @@ -# Define dependencies between Arduino Libraries which are submodules -CMP_Adafruit_BME280_Library_DEPENDS := Adafruit_Sensor -CMP_Adafruit_SSD1306_DEPENDS := Adafruit_GFX -CMP_Adafruit_ST7735_DEPENDS := Adafruit_GFX -CMP_HMC5883L_DEPENDS := I2Cdev -CMP_IR_DEPENDS := RingBufCPP diff --git a/Sming/Libraries/si4432/README.md b/Sming/Libraries/si4432/README.md new file mode 100644 index 0000000000..2d3df8033a --- /dev/null +++ b/Sming/Libraries/si4432/README.md @@ -0,0 +1,9 @@ +# Si4432 RF Transceiver + +SI4432 library for Arduino - v0.1 + +Please note that Library uses standard SS pin for NSEL pin on the chip. This is 53 for Mega, 10 for Uno. + +made by Ahmet (theGanymedes) Ipkin (2014) + +https://github.com/ADiea/si4432.git diff --git a/Sming/Makefile b/Sming/Makefile index 11a0e7bfc4..7f479732d5 100644 --- a/Sming/Makefile +++ b/Sming/Makefile @@ -25,7 +25,7 @@ DOXYGEN := $(shell command -v doxygen 2> /dev/null) ##@Cleaning .PHONY: dist-clean -dist-clean: submodules-clean samples-clean ##Clean everything for all arch/build types +dist-clean: submodules-clean samples-clean docs-clean ##Clean everything for all arch/build types -$(Q) rm -rf out .PHONY: clean @@ -38,47 +38,35 @@ components-clean: ##Remove generated Component (user) libraries -$(Q) rm -f $(USER_LIBDIR)/* -$(Q) rm -rf $(OUT_BASE) + +ALL_SUBMODULES = $(ListSubmodules) + .PHONY: submodules-clean submodules-clean: ##Reset state of all third-party submodules @echo Cleaning all submodules... - -$(Q) rm -rf $(ListSubmodules) - -$(Q) rm -rf $(addprefix $(BUILD_BASE),$(ListSubmodules)) - $(Q) $(GIT) checkout $(ListSubmodules) - - -##@Building - -.PHONY: test -test: Basic_Blink Basic_rBoot Basic_Ssl Basic_HwPWM ##Build a few sample applications + -$(Q) rm -rf $(ALL_SUBMODULES) + -$(Q) rm -rf $(addprefix $(BUILD_BASE),$(ALL_SUBMODULES)) + $(Q) $(GIT) checkout $(ALL_SUBMODULES) -# => Documentation -DOCS_DIR := ../docs +.PHONY: docs-clean +docs-clean: ##Clean the Sming documentation + $(Q) $(MAKE) -C ../docs clean -.PHONY: wiki api docs -docs: wiki api ##Build the Sming API and Wiki documentation -wiki: $(DOCS_DIR)/wiki/Home.md -api: $(DOCS_DIR)/api/sming/index.html -$(DOCS_DIR)/wiki/Home.md: - $(vecho) "No Wiki submodule found. Using git to fetch it..." - $(Q) $(GIT) submodule update --init $(DOCS_DIR)/wiki +##@Building -$(DOCS_DIR)/api/error.log: -ifndef DOXYGEN - $(error doxygen not found - not building API docs) -endif - $(Q) mkdir -p $(DOCS_DIR)/api - $(Q) cd $(DOCS_DIR) && doxygen 2>api/stderr.log 1>api/doxygen.log +# Pull in all submodules, regardless of whether they're used or not +.PHONY: submodules +submodules: $(ALL_SUBMODULES:=/.submodule) ##Fetch all third-party submodules (but do not build) -$(DOCS_DIR)/api/sming/index.html: $(DOCS_DIR)/api/error.log - $(vecho) "Undocumented compounds: $(shell grep "Compound.*is not documented" $(DOCS_DIR)/api/error.log | wc -l)" - $(vecho) "Undocumented members: $(shell grep "Member.*is not documented" $(DOCS_DIR)/api/error.log | wc -l) " - $(vecho) "Undocumented parameters: $(shell grep "The following parameters of .* are not documented" $(DOCS_DIR)/api/error.log | wc -l) " - $(vecho) "Open in your browser: file://$(abspath $@)" +.PHONY: test +test: Basic_Blink Basic_rBoot Basic_Ssl Basic_HwPWM ##Build a few sample applications +.PHONY: docs +docs: submodules ##Build the Sming documentation + $(Q) $(MAKE) -C ../docs html -##@Building # For integration testing both samples and tests are moved outside of the repo. SMING_PROJECTS_DIR ?= $(abspath $(SMING_HOME)/..) diff --git a/Sming/Platform/AccessPoint.h b/Sming/Platform/AccessPoint.h index 10eed4e727..e4985bce26 100644 --- a/Sming/Platform/AccessPoint.h +++ b/Sming/Platform/AccessPoint.h @@ -70,7 +70,7 @@ class AccessPointClass : protected ISystemReadyHandler bool setIP(IPAddress address); /** @brief Get WiFi AP MAC address - * @param optional separator between bytes (e.g. ':') + * @param sep separator between bytes (e.g. ':') * @retval String WiFi AP MAC address */ String getMAC(char sep = '\0'); diff --git a/Sming/Platform/RTC.h b/Sming/Platform/RTC.h index fdac7faac7..7b5ebf0648 100644 --- a/Sming/Platform/RTC.h +++ b/Sming/Platform/RTC.h @@ -63,3 +63,5 @@ class RtcClass * @ingroup rtc */ extern RtcClass RTC; + +/** @} */ diff --git a/Sming/Platform/Station.h b/Sming/Platform/Station.h index 8c88bfa2b2..dd95aa320d 100644 --- a/Sming/Platform/Station.h +++ b/Sming/Platform/Station.h @@ -72,13 +72,13 @@ typedef Delegate WPSConfigDelegate; #endif /** @} */ +/** @brief WiFi station class + * @addtogroup wifi_sta + * @{ + */ class StationClass : protected ISystemReadyHandler { public: - /** @brief WiFi station class - * @addtogroup wifi_sta - * @{ - */ StationClass() { System.onReady(this); @@ -158,7 +158,7 @@ class StationClass : protected ISystemReadyHandler IPAddress getIP(); /** @brief Get WiFi station MAC address - * @param optional separator between bytes (e.g. ':') + * @param sep Optional separator between bytes (e.g. ':') * @retval String WiFi station MAC address */ String getMAC(char sep = '\0'); diff --git a/Sming/Platform/WDT.h b/Sming/Platform/WDT.h index f3aa88ad39..df02bd5b17 100644 --- a/Sming/Platform/WDT.h +++ b/Sming/Platform/WDT.h @@ -58,3 +58,5 @@ class WDTClass : protected ISystemReadyHandler * @endcode */ extern WDTClass WDT; + +/** @} */ diff --git a/Sming/README.rst b/Sming/README.rst new file mode 100644 index 0000000000..eca46c0d0e --- /dev/null +++ b/Sming/README.rst @@ -0,0 +1,98 @@ +Sming (main) +============ + +This is the main Sming Component containing all architecture-independent code. +All architecture-specific stuff is in either :component-esp8266:`sming-arch` or :component-host:`sming-arch`. + +Serial baud rate +---------------- + +.. envvar:: COM_SPEED + + Default baud rate for serial port. + + This will recompile your application to use the revised baud rate. + Note that this will change the default speed used for both flashing and serial comms. + See also :component-esp8266:`esptool` and :component:`terminal` for further details. + +The default rate for serial ports is 115200 baud. You can change it like this: + +.. code-block:: bash + + make COM_SPEED=921600 + + +Debug information log level and format +-------------------------------------- + +.. envvar:: DEBUG_VERBOSE_LEVEL + + When compiled in debug mode (:envvar:SMING_RELEASE undefined) there are four debug levels in increasing level of verbosity: + + * 0: errors + * 1: warnings + * 2: information (default) + * 3: debug + +Change it like this: + +.. code-block:: bash + + make DEBUG_VERBOSE_LEVEL=3 + + +.. envvar:: DEBUG_PRINT_FILENAME_AND_LINE + + Set this to 1 to include the filename and line number in every line of debug output. + This will require extra space on flash. + +.. note:: + If you change these settings and want them applied to Sming, not just your project, then you'll + need to recompile all components like this: + + .. code-block:: bash + + make components-clean + make DEBUG_VERBOSE_LEVEL=3 + + +Release builds +-------------- + +.. envvar:: SMING_RELEASE + + By default, this value is undefined to produce a build with debug output. + To build for release, do this: + + .. code-block:: bash + + make SMING_RELEASE=1 + + This remains in force until you change it back: + + .. code-block:: bash + + make SMING_RELEASE= + + +Command Executor +---------------- + +Default: ON. This feature enables +execution of certain commands by registering token handlers for text +received via serial, websocket or telnet connection. If this feature +is not used additional RAM/Flash can be obtained by setting +``ENABLE_CMD_EXECUTOR=0``. This will save ~1KB RAM and ~3KB of flash +memory. + +.. doxygengroup:: commandhandler + + +Components +---------- + + .. toctree:: + :glob: + :maxdepth: 1 + + Components/*/index diff --git a/Sming/System/include/gdb/gdb_syscall.h b/Sming/System/include/gdb/gdb_syscall.h index 9d87f9d500..2fef00b506 100644 --- a/Sming/System/include/gdb/gdb_syscall.h +++ b/Sming/System/include/gdb/gdb_syscall.h @@ -201,7 +201,6 @@ static inline int gdb_syscall_open(const char* filename, int flags, int mode, gd /** * @brief Close a host file * @param fd File handle - * @param flags A combination of O_* flags defined in fcntl.h (e.g. O_RDONLY, O_CREAT, etc) * @param callback * @param param * @retval int diff --git a/Sming/System/include/stringutil.h b/Sming/System/include/stringutil.h index 320b19a159..7ed86754b4 100644 --- a/Sming/System/include/stringutil.h +++ b/Sming/System/include/stringutil.h @@ -21,10 +21,10 @@ extern "C" { #include "stddef.h" -/** Return pointer to occurence of substring in string. Case insensitive. - * \param[in] pString string to work with - * \param[in] pToken string to locate - * \return pointer to first occurence in of pToken in pString or NULL if not found +/** @brief Return pointer to occurence of substring in string. Case insensitive. + * @param[in] pString string to work with + * @param[in] pToken string to locate + * @retval const char* pointer to first occurence in of pToken in pString or NULL if not found */ const char* strstri(const char* pString, const char* pToken); @@ -35,8 +35,12 @@ const char* strstri(const char* pString, const char* pToken); int strcasecmp(const char* s1, const char* s2); /** @brief Returns a pointer to the first occurrence of @var{needle} (length @var{needle_len}) in @var{haystack} (length @var{haystack_len}). - @retval void* @code{NULL} if not found. - @note non-ANSI GNU C library extension + * @param haystack + * @param haystacklen + * @param needle + * @param needlelen + * @retval void* @code{NULL} if not found. + * @note non-ANSI GNU C library extension */ void* memmem(const void* haystack, size_t haystacklen, const void* needle, size_t needlelen); #endif diff --git a/Sming/Wiring/FlashString.h b/Sming/Wiring/FlashString.h index 31722e7608..f9981bfb7a 100644 --- a/Sming/Wiring/FlashString.h +++ b/Sming/Wiring/FlashString.h @@ -84,7 +84,7 @@ #include "WString.h" -/** @Brief Define a FlashString +/** @brief Define a FlashString * @param _name variable to identify the string * @param _str content of the string * @note the whole thing is word-aligned @@ -95,7 +95,7 @@ DEFINE_FSTR_STRUCT(_##_name, _str); \ const FlashString& _name PROGMEM = _##_name.fstr; -/** @Brief Define a FlashString for local (static) use +/** @brief Define a FlashString for local (static) use * @param _name variable to identify the string * @param _str content of the string */ @@ -221,7 +221,7 @@ struct FlashString { } /** @brief Check for equality with a C-string - * @param str + * @param cstr * @retval bool true if strings are identical * @note loads string into a stack buffer for the comparison, no heap required */ diff --git a/Sming/build.mk b/Sming/build.mk index 012af04ddc..9c4be40727 100644 --- a/Sming/build.mk +++ b/Sming/build.mk @@ -198,7 +198,7 @@ define PrintHelp } /^##@/ { \ group = $$2; \ groups[group] = group; \ - } /^[a-zA-Z_-]+:.*?##/ { \ + } /^[a-zA-Z0-9_-]+:.*?##/ { \ targets[$$1, group] = $$2; \ } \ END { \ @@ -232,3 +232,39 @@ $(shell mkdir -p $(dir $1); echo >> $1; $(foreach v,$2,echo '$v = $($v)' >> $1;) ) endef + + +## PATCHING + +# Apply patch to a submodule +# $1 -> patch file with relative path +define ApplyPatch + $(GIT) apply -v $1 --ignore-whitespace --whitespace=nowarn +endef + +# If there's a patch for this submodule, apply it +# We look for patch in .. and in ../.patches +# If a matching subdirectory is found in ../.patches/ then the contents +# are copied, overwriting any existing files with the same name +# $1 -> submodule path +# $2 -> name of patch file +define TryApplyPatch + cd $1 && if [ -f ../$2 ]; then \ + $(call ApplyPatch,../$2); \ + elif [ -f ../.patches/$2 ]; then \ + $(call ApplyPatch,../.patches/$2); \ + fi && \ + if [ -d ../.patches/$(basename $2)/ ]; then \ + cp -f ../.patches/$(basename $2)/* . ; \ + fi +endef + +# Update and patch submodule +# Patch file is either in submodule parent directory itself or subdirectory .patches from there +%/.submodule: + $(info ) + $(info Fetching submodule '$*' ...) + $(Q) cd $(abspath $*/..) && (rm -rf $(*F); $(GIT) submodule update --init --force --recursive $(*F)) + $(Q) $(call TryApplyPatch,$*,$(*F).patch) + $(Q) touch $@ + diff --git a/Sming/building.md b/Sming/building.md deleted file mode 100644 index 029ccfa0fb..0000000000 --- a/Sming/building.md +++ /dev/null @@ -1,375 +0,0 @@ -# Sming makefile build system - -## Introduction - -This guide is provided to assist with understanding, developing and modifying the build system. - -A Sming project is built from a set of static libraries (object archives). Typically the application code is one library, built from the user's source code, whilst the other libraries are common to all projects and stored in a separate, shared location. - -Until recently Sming itself has always been built as one large library, but this is now broken into a number of discrete Component libraries. The concept is borrowed from Espressif's ESP-IDF build system and whilst it there are similarities the two systems are completely independent. - -## Building applications - -### Setup - -These are the main variables you need to be aware of: - -`SMING_HOME` must be set to the full path of the `Sming` directory. - -`SMING_ARCH` Defines the target architecture: - -* **Esp8266** The default if not specified. `ESP_HOME` must also be provided to locate SDK & tools. - -* **Esp32** {todo} - -* **Host** builds a version of the library for native host debugging on Linux or Windows - -These variables are available for application use: - -`PROJECT_DIR` Path to the project's root source directory, without trailing path separator. This variable is available within makefiles, but is also provided as a #defined C string to allow references to source files within application code, such as with the `IMPORT_FSTR` macro. - - -### Converting existing projects - -Instead of `Makefile-user.mk` a project should provide a `component.mk`. To convert to the new style: - -1. Copy `Makefile` and `component.mk` from the `Basic_Blink` sample project -2. Copy any customisations from `Makefile-user.mk` into `component.mk` file. (Or, rename `Makefile-user.mk` to `component.mk` then edit it.) -3. Delete `Makefile-user.mk` -4. If the project uses any Arduino libraries, set the `ARDUINO_LIBRARIES` variable - -**Targets** You can add your own targets to component.mk as usual. It's a good idea to add a comment for the target, like this: - -``` -##@Building - -.PHONY: mytarget -mytarget: ##This is my target -``` - -When you type `make help` it will appear in the list. - -If you need a target to be added as a dependency to the main application build, add it to `CUSTOM_TARGETS` - the `Basic_Serial` sample contains a simple example of this. - -**Arduino Libraries** If your project uses any Arduino libraries, you must set `ARDUINO_LIBRARIES` appropriately. - -**Source files** Use `COMPONENT_SRCDIRS` instead of `MODULES`. Use `COMPONENT_SRCFILES` to add individual files. - -**Include paths** Use `COMPONENT_INCDIRS` instead of `EXTRA_INCDIR`. - -See [component.mk](#component-configuration) for a full list of variables. - - -### Building - -You should normally work from the project directory. Examples: - -* Type `make` to build the project and any required Components. To speed things up, use parallel building, e.g. `make -j5` will build using a maximum of 5 concurrent jobs. The optimum value for this is usually (CPU CORES + 1). Using `make -j` will use unlimited jobs, but can cause problems in virtual environments. - -* Type `make help` from the project directory to get a list of available build targets. - -To switch to a different build architecture, for example: - -* Type `make SMING_ARCH=Host` to build the project for the host emulator -* Type `make flash` to copy any SPIFFS image (if enabled) to the virtual flash, and run the application. (Note that you don't need to set SMING_ARCH again, the value is cached.) - -To inspect the current build configuration, type `make list-config`. - - -### Configuration variables - -Configuration variables should be set in the project's component.mk file. If appropriate, they can also be set as environment variables. - -During development, the easiest way to change variables is on the `make` command line. These are cached so persist between make sessions, and will override any values set in your project's `component.mk` file. For example: - -* Type `make SPIFF_BIN=test-rom` to build the project and (if enabled) create a SPIFFS image file called `test-rom.bin` -* Type `make flash COM_PORT=COM4 SPI_MODE=dio SPI_SIZE=4M` to flash the project and `test-rom` SPIFFS image using the provided flash memory settings -* Next time you type `make flash`, the same settings will be used, no need to type them again - -A separate cache is maintained for each build type (arch + release/debug). For example: - -* Type `make SMING_RELASE=1 list-config` to switch to release build and display the active configuration - -Type `make config-clean` to clear all caches and revert to defaults. - -For reference, a copy of all build variables are stored in a file with each firmware image created in the 'firmware' directory. - - -### Component repositories - -Placing Components in a common location allows them to be used by multiple projects. To set up your own Component repository, create a directory in a suitable location which will contain your Components and set `COMPONENT_SEARCH_DIRS` to the full path of that directory. For example: - -``` - export COMPONENT_SEARCH_DIRS=/opt/shared/Components - - |_ opt - |_ shared - |_ Components # The repository - |_ MyComponent - |_ AnotherComponent - |_ spiffs # Will be used instead of Sming version -``` - -User repositories are searched first, which allows replacement of any Component for a project. In this example, our `spiffs` component will be selected instead of the one provided with Sming. - - -## Directory layout - -The main Sming repo. is laid out like this: - -``` -Directory/File Contents ---------- ----- -------- - -|_ sming - .appveyor.yml CI testing (Windows) - .travis.yml CI testing (Linux) - |_ .appveyor CI scripts (Windows) - |_ .travis CI scripts (Linux) - |_ docs Sming documentation - |_ samples Samples to demonstrate specific Sming features or libraries - |_ Sming - Makefile Builds documentation, performs global actions on the framework - project.mk Main makefile to build a project - build.mk Defines the build environment - component.mk Sming Component definition file - component-wrapper.mk Used to build each Component using a separate make instance - |_ Arch Architecture-specific makefiles and code - |_ Esp8266 - sming.mk Defines architecture-specific Components and libraries - app.mk Links the project, create output binaries and perform architecture-specific actions - build.mk Architecture-specific build definitions, such as compiler paths - |_ Compiler - |_ Components - |_ Core - |_ Platform - |_ System - |_ Tools Pre-compiled or scripted tools - |_ Esp32 - ... - |_ Host - ... - |_ Components Framework support code, not to be used directly by applications - |_ Core Main framework core - |_ Libraries Arduino Libraries - ... - |_ out All generated shared files are written here - |_ Esp8266 The Arch - |_ debug The build type - |_ build Intermediate object files - |_ Lib Generated libraries - |_ tools Generated tools - |_ release - ... - |_ Host - ... - |_ Platform System-level classes - ... - |_ Services Modules not considered as part of Core - ... - |_ System Common framework low-level system code - |_ include - |_ Wiring - ... - |_ tests Integration test applications - ... - -``` - -A typical Project looks like this: - -``` -|_ Basic_Blink - Makefile Just calls Makefile-app.mk - component.mk Project-specific definitions - |_ app Default application source directory - |_ include Default application include directory - |_ out All generated shared files are written here - |_ Esp8266 The Arch - |_ debug The build type - |_ build Intermediate object files - |_ firmware Target output files - |_ Lib Generated libraries - |_ tools Generated tools - |_ release - ... - |_ Host - ... -``` - - -## Components - -The purpose of a Component is to encapsulate related elements for selective inclusion in a project, for easy sharing and re-use: - -* **Shared Library** with associated header files -* **App Code** Source files to be compiled directly into the user's project -* **Header files** without any associated source or library -* **Build targets** to perform specific actions, such as flashing binary data to hardware - -By default, a Component is built into a shared library using any source files found in the base or `src` directories. All Arduino Libraries are built as Components. Note that the application is also built as a Component library, but the source directory defaults to `app` instead of `src`. - -Components are referred to simply by name, defined by the directory in which it is stored. The Component itself is located by looking in all the directories listed by `COMPONENT_SEARCH_DIRS`, which contains a list of repositories. (Every sub-directory of a repository is considered to be a Component.) If there are Components with the same name in different search directories, the first one found will be used. - -Components are customised by providing an optional `component.mk` file. - -You can see details of all Components used in a project using `make list-components`. Add `V=1` to get more details. - -Note that the application itself is also built as a Component, and may be configured in a similar way to any other Component. - -### Library variants - -Libraries can often be built using different option settings, so a mechanism is required to ensure that libraries (including the application) are rebuilt if those settings change. This is handled using _variants_, which modifies the library name using a hash of the settings values. Each variant gets its own build sub-directory so incremental building works as usual. - -There are several types of config variable: - -Variable type | Cached? | Rebuild Component? | Rebuild application? | Relink application ---- | --- | --- | --- | --- -COMPONENT | Y | Y | Y | Y -CONFIG | Y | N | Y | Y -RELINK | Y | N | N | Y -CACHE | Y | N | N | N -DEBUG | N | N | N | N - -Variables are usually defined in the context of a Component, in the component.mk file. All Components see the full configuration during building, not just their own variables. - -The type of a configuration variable is defined by adding its _name_ to one of the following lists: - -`CONFIG_VARS` The Application library derives its variant from these variables. Use this type if the Component doesn't require a rebuild, but the application does. - -`COMPONENT_VARS` A Component library derives its variant from these variables. Any variable which requires a rebuild of the Component library itself must be listed. For example, the `esp-open-lwip` Component defines this as `ENABLE_LWIPDEBUG ENABLE_ESPCONN`. The default values for these produces `ENABLE_LWIPDEBUG=0 ENABLE_ESPCONN=0`, which is hashed (using MD5) to produce `a46d8c208ee44b1ee06f8e69cfa06773`, which is appended to the library name. - -`RELINK_VARS` Code isn't re-compiled, but libraries are re-linked and firmware images re-generated if any of these variables are changed. For example, `make RBOOT_ROM_0=new-rom-file` rewrites the firmware image using the given filename. (Also, as the value is cached, if you then do `make flashapp` that same iamge gets flashed.) - -`CACHE_VARS` These variables have no effect on building, but are cached. Variables such as `COM_SPEED_ESPTOOL` fall into this category. - -`DEBUG_VARS` are generally for information only, and are not cached (except for `SMING_ARCH` and `SMING_RELEASE`). - - -### Dependencies - -`COMPONENT_DEPENDS` identifies a list of Components upon which this one depends. These are established as pre-requisites so will trigger a rebuild. In addition, all dependent `COMPONENT_VARS` are (recursively) used in creation of the library hash. - -For example, the `axtls-8266` Component declares `SSL_DEBUG` as a `COMPONENT_VAR`. Because `Sming` depends on `sming-arch`, which in turn depends on `axtls-8266`, all of these Components get rebuilt as different variants when `SSL_DEBUG` changes values. The project code (`App` Component) also gets rebuilt as it implicitly depends on `Sming`. - - -### Component configuration - -The `component.mk` is parsed twice, first from the top-level makefile and the second time from the sub-make which does the actual building. A number of variables are used to define behaviour. - -These values are for reference only and should not be modified. - -`COMPONENT_NAME` Name of the Component -`COMPONENT_PATH` Base directory path for Component, no trailing path separator -`COMPONENT_BUILD_DIR` The current directory. This should be used if the Component provides any application code or targets to ensure it is built in the correct directory (but not by this makefile). -`COMPONENT_LIBDIR` Location to store created Component (shared) libraries -`COMPONENT_VARIANT` Name of the library to build -`COMPONENT_LIBPATH` Full path to the library to be built - -These values may be used to customise Component behaviour and may be changed as required. - -`COMPONENT_LIBNAME` By default, the library has the same name as the Component but can be changed if required. Note that this will be used as the stem for any variants. -Set `COMPONENT_LIBNAME :=` if the Component doesn't create a library. If you don't do this, a default library will be built but will be empty if no source files are found. - -`COMPONENT_TARGETS` Set this to any additional targets to be built as part of the Component, prefixed with `$(COMPONENT_RULE)`. If targets should be built for each application, use `CUSTOM_TARGETS` instead. See `spiffs` for an example. - -`COMPONENT_RULE` This is a special value used to prefix any custom targets which are to be built as part of the Component. The target must be prefixed by `$(COMPONENT_RULE)` without any space between it and the target. This ensures the rule only gets invoked during a component build, and is ignored by the top-level make. - -`COMPONENT_SUBMODULES` Relative paths to dependent submodule directories for this Component. These will be fetched/patched automatically before building. The patch file should be located in the submodule's parent directory (usually the Component directory itself). If the Component is itself a submodule, then patch files must be placed in `../.patches`. A `.submodule` file is created once the submodule has been fetched and successfully patched. - -`COMPONENT_SRCDIRS` Locations for source code relative to COMPONENT_PATH (defaults to ". src") - -`COMPONENT_INCDIRS` Include directories available when building ALL Components (not just this one). Paths may be relative or absolute. - -`INCDIR` The resultant set of include directories used to build this Component. Will contain include directories specified by all other Components in the build. May be overridden if required. - -`COMPONENT_APPCODE` List of directories containing source code to be compiled directly with the application. (Ignore in the project.mk file - use `COMPONENT_SRCDIRS` instead). - -`CUSTOM_BUILD` Set to 1 if providing an alternative build method. See [Custom building](#custom-building) section. - -`EXTRA_OBJ` Absolute paths to any additional binary object files to be added to the Component archive library. - -`COMPONENT_DEPENDS` Set to the name(s) of any dependent Components. - -`EXTRA_LIBS` Set to names of any additional libraries to be linked. - -`EXTRA_LDFLAGS` Set to any additional flags to be used when linking. - -These values are global so must only be appended to (with `+=`) , never overwritten. - -`CUSTOM_TARGETS` Identifies targets to be built along with the application. These will be invoked directly by the top-level make. - -`GLOBAL_CFLAGS` Use only if you need to provide additional compiler flags to be included when building all Components (including Application) and custom targets. - -`APP_CFLAGS` Used when building application and custom targets. - - -**IMPORTANT NOTE** - -During initial parsing, many of these variables (specifically, the `COMPONENT_xxx` ones) _do not_ keep their values. For this reason it is usually best to use simple variable assignment using `:=`. - -For example, in `Esp8266/Components/gdbstub` we define `GDB_CMDLINE`. It may be tempting to do this: - -``` -GDB_CMDLINE = trap '' INT; $(GDB) -x $(COMPONENT_PATH)/gdbcmds -b $(COM_SPEED_GDB) -ex "target remote $(COM_PORT_GDB)" -``` - -That won't work! By the time `GDB_CMDLINE` gets expanded, `COMPONENT_PATH` could contain anything. We need `GDB_CMDLINE` to be expanded only when used, so the solution is to take a simple copy of `COMPONENT_PATH` and use it instead, like this: - -``` -GDBSTUB_DIR := $(COMPONENT_PATH) -GDB_CMDLINE = trap '' INT; $(GDB) -x $(GDBSTUB_DIR)/gdbcmds -b $(COM_SPEED_GDB) -ex "target remote $(COM_PORT_GDB)" -``` - - -### Building - -For faster builds use make with the `-j` (jobs) feature of make. It is usually necessary to specify a limit for the number of jobs, especially on virtual machines. There is usually no point in using a figure greater than (CPU cores + 1). The CI builds use `-j3`. - -Note that `Makefile-app.mk` enforces sequential building to ensure submodules are fetched and patched correctly. This also ensures that only one Component is built at a time which keeps the build logs quite clean and easy to follow. - -Components can be rebuilt and cleaned individually. For example: - -* `make spiffs-build` runs the Component 'make' for spiffs, which contains the spiffs library and spiffy tool. -* `make spiffs-clean` removes all intermediate build files for the Component -* `make spiffs-rebuild` cleans and then re-builds the Component - -By default, a regular `make` performs an incremental build on the application, which invokes a separate (recursive) make for the `App` Component. All other Components only get built if any of their targets don't exist (e.g. variant library not yet built). This makes application building faster and less 'busy', which is generally preferable for regular application development. For Component development this behaviour can be changed using the `FULL_COMPONENT_BUILD` variable (which is cached). Examples: - -* `make FULL_COMPONENT_BUILD=lwip` will perform an incremental build on the `lwip` Component -* `make FULL_COMPONENT_BUILD=1` will incrementally build all Components - - -### Custom Building - -To use an external makefile or other build system (such as CMake) to create the Component library, or to add additional shared libraries or other targets, customise the `component.mk` file as follows: - -1. Set `CUSTOM_BUILD=1` -2. Define the custom rule, prefixed with `$(COMPONENT_RULE)`. Note that Components are built using a separate make instance with the current directory set to the build output directory, not the source directory. - -It is important that the rule uses the provided values for `COMPONENT_LIBNAME`, `COMPONENT_LIBPATH` and `COMPONENT_LIBDIR` so that variant building, cleaning, etc. work correctly. See below under 'Building', and the Host `lwip` Component for an example. - -Components are built using a make instance with the current directory set to the build output directory, not the source directory. If any custom building is done then these variables must be obeyed to ensure variants, etc. work as expected: - -`COMPONENT_LIBNAME` as provided by component.mk, defaults to component name, e.g. `Sming` -`COMPONENT_LIBHASH` hash of the component variables used to create unique library names, e.g. `13cd2ddef79fda79dae1644a33bf48bb` -`COMPONENT_VARIANT` name of the library to be built, including hash. e.g. `Sming-13cd2ddef79fda79dae1644a33bf48bb` -`COMPONENT_LIBDIR` directory where any generated libraries must be output, e.g. `/home/user/sming/Sming/out/Esp8266/debug/lib/` -`COMPONENT_LIBPATH` full path to the library to be created, e.g. `/home/user/sming/Sming/out/Esp8266/debug/lib/clib-Sming-13cd2ddef79fda79dae1644a33bf48bb.a` -`COMPONENT_BUILDDIR` where to write intermediate object files, e.g. `/home/user/sming/Sming/out/Esp8266/debug/build/Sming/Sming-13cd2ddef79fda79dae1644a33bf48bb` - -### Porting existing libraries - -to be completed - - -## Known Issues - -**Cleaning** Components are not cleaned unless defined. e.g. `make axtls-8266-clean` will fail unless you also specify `ENABLE_SSL=1`. - -**Empty libraries** Components without any source code produce an empty library. This is because, for simplicity, we don't want to add a component.mk to every Arduino library. - -**Empty Component directories** Every sub-directory in the `COMPONENT_SEARCH_DIRS` is interpreted as a Component. For example, `spiffs` was moved out of Arch/Esp8266/Components but if an empty directory called 'spiffs' still remains then it will be picked up instead of the main one. These sorts of issues can be checked using `make list-components` to ensure the correct Component path has been selected. - -**Components as submodules** All component.mk files must be available for parsing. If they are contained in a GIT submodule then that must be fetched first. Some settings may be specified in a components.mk file instead. - diff --git a/Sming/building.rst b/Sming/building.rst new file mode 100644 index 0000000000..f0669e0b33 --- /dev/null +++ b/Sming/building.rst @@ -0,0 +1,614 @@ +Sming makefile build system +=========================== + +Introduction +------------ + +This guide is provided to assist with understanding, developing and +modifying the build system. + +A Sming project is built from a set of static libraries (object +archives). Typically the application code is one library, built from the +user’s source code, whilst the other libraries are common to all +projects and stored in a separate, shared location. + +Until recently Sming itself has always been built as one large library, +but this is now broken into a number of discrete Component libraries. +The concept is borrowed from Espressif’s ESP-IDF build system and whilst +it there are similarities the two systems are completely independent. + +Building applications +--------------------- + +Setup +~~~~~ + +These are the main variables you need to be aware of: + +``SMING_HOME`` must be set to the full path of the ``Sming`` directory. + +``SMING_ARCH`` Defines the target architecture: + +- **Esp8266** The default if not specified. ``ESP_HOME`` must also be + provided to locate SDK & tools. + +- **Esp32** {todo} + +- **Host** builds a version of the library for native host debugging on + Linux or Windows + +These variables are available for application use: + +``PROJECT_DIR`` Path to the project’s root source directory, without +trailing path separator. This variable is available within makefiles, +but is also provided as a #defined C string to allow references to +source files within application code, such as with the ``IMPORT_FSTR`` +macro. + +Converting existing projects +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Instead of ``Makefile-user.mk`` a project should provide a +``component.mk``. To convert to the new style: + +1. Copy ``Makefile`` and ``component.mk`` from the ``Basic_Blink`` + sample project +2. Copy any customisations from ``Makefile-user.mk`` into + ``component.mk`` file. (Or, rename ``Makefile-user.mk`` to + ``component.mk`` then edit it.) +3. Delete ``Makefile-user.mk`` +4. If the project uses any Arduino libraries, set the + ``ARDUINO_LIBRARIES`` variable + +**Targets** You can add your own targets to component.mk as usual. It’s +a good idea to add a comment for the target, like this: + +:: + + ##@Building + + .PHONY: mytarget + mytarget: ##This is my target + +When you type ``make help`` it will appear in the list. + +If you need a target to be added as a dependency to the main application +build, add it to ``CUSTOM_TARGETS`` - the ``Basic_Serial`` sample +contains a simple example of this. + +**Arduino Libraries** If your project uses any Arduino libraries, you +must set ``ARDUINO_LIBRARIES`` appropriately. + +**Source files** Use ``COMPONENT_SRCDIRS`` instead of ``MODULES``. Use +``COMPONENT_SRCFILES`` to add individual files. + +**Include paths** Use ``COMPONENT_INCDIRS`` instead of ``EXTRA_INCDIR``. + +See `component.mk <#component-configuration>`__ for a full list of +variables. + +Building +~~~~~~~~ + +You should normally work from the project directory. Examples: + +- Type ``make`` to build the project and any required Components. To + speed things up, use parallel building, e.g. \ ``make -j5`` will + build using a maximum of 5 concurrent jobs. The optimum value for + this is usually (CPU CORES + 1). Using ``make -j`` will use unlimited + jobs, but can cause problems in virtual environments. + +- Type ``make help`` from the project directory to get a list of + available build targets. + +To switch to a different build architecture, for example: + +- Type ``make SMING_ARCH=Host`` to build the project for the host + emulator +- Type ``make flash`` to copy any SPIFFS image (if enabled) to the + virtual flash, and run the application. (Note that you don’t need to + set SMING_ARCH again, the value is cached.) + +To inspect the current build configuration, type ``make list-config``. + +Configuration variables +~~~~~~~~~~~~~~~~~~~~~~~ + +Configuration variables should be set in the project’s component.mk +file. If appropriate, they can also be set as environment variables. + +During development, the easiest way to change variables is on the +``make`` command line. These are cached so persist between make +sessions, and will override any values set in your project’s +``component.mk`` file. For example: + +- Type ``make SPIFF_BIN=test-rom`` to build the project and (if + enabled) create a SPIFFS image file called ``test-rom.bin`` +- Type ``make flash COM_PORT=COM4 SPI_MODE=dio SPI_SIZE=4M`` to flash + the project and ``test-rom`` SPIFFS image using the provided flash + memory settings +- Next time you type ``make flash``, the same settings will be used, no + need to type them again + +A separate cache is maintained for each build type (arch + +release/debug). For example: + +- Type ``make SMING_RELASE=1 list-config`` to switch to release build + and display the active configuration + +Type ``make config-clean`` to clear all caches and revert to defaults. + +For reference, a copy of all build variables are stored in a file with +each firmware image created in the ‘firmware’ directory. + +Component repositories +~~~~~~~~~~~~~~~~~~~~~~ + +Placing Components in a common location allows them to be used by +multiple projects. To set up your own Component repository, create a +directory in a suitable location which will contain your Components and +set ``COMPONENT_SEARCH_DIRS`` to the full path of that directory. For +example: + +.. code-block:: text + + |_ opt/ + |_ shared/ + |_ Components/ The repository + |_ MyComponent/ + |_ AnotherComponent/ + |_ spiffs/ Will be used instead of Sming version + +User repositories are searched first, which allows replacement of any +Component for a project. In this example, our ``spiffs`` component will +be selected instead of the one provided with Sming. + +Directory layout +---------------- + +The main Sming repo. is laid out like this: + +.. code-block:: text + + |_ sming/ + |_ .appveyor.yml CI testing (Windows) + |_ .travis.yml CI testing (Linux) + |_ .appveyor/ CI scripts (Windows) + |_ .travis CI scripts (Linux) + |_ docs/ Sming documentation + |_ samples/ Samples to demonstrate specific Sming features or libraries + |_ Sming/ + | |_ Makefile Builds documentation, performs global actions on the framework + | |_ project.mk Main makefile to build a project + | |_ build.mk Defines the build environment + | |_ component.mk Sming Component definition file + | |_ component-wrapper.mk Used to build each Component using a separate make instance + | |_ Arch/ Architecture-specific makefiles and code + | | |_ Esp8266/ + | | | |_ sming.mk Defines architecture-specific Components and libraries + | | | |_ app.mk Link the project, create output binaries + | | | | and perform architecture-specific actions + | | | |_ build.mk Architecture-specific build definitions, such as compiler paths + | | | |_ Compiler/ + | | | |_ Components/ + | | | |_ Core/ + | | | |_ Platform/ + | | | |_ System/ + | | | |_ Tools/ Pre-compiled or scripted tools + | | |_ Esp32/ + | | | |_ ... + | | |_ Host/ + | | |_ ... + | |_ Components/ Framework support code, not to be used directly by applications + | |_ Core/ Main framework core + | |_ Libraries/ Arduino Libraries + | | |_ ... + | |_ out/ All generated shared files are written here + | | |_ Esp8266/ The Arch + | | | |_ debug/ The build type + | | | |_ build/ Intermediate object files + | | | | |_ Lib/ Generated libraries + | | | | |_ tools/ Generated tools + | | | |_ release/ + | | | |_ ... + | | |_ Host/ + | | |_ ... + | |_ Platform/ System-level classes + | | |_ ... + | |_ Services/ Modules not considered as part of Core + | | |_ ... + | |_ System/ Common framework low-level system code + | | |_ include/ + | |_ Wiring/ + | |_ ... + |_ tests/ Integration test applications + |_ ... + +A typical Project looks like this: + +.. code-block:: text + + |_ Basic_Blink/ + |_ Makefile Just includes project.mk + |_ component.mk Project-specific definitions + |_ app/ Default application source directory + |_ include/ Default application include directory + |_ out/ All generated shared files are written here + |_ Esp8266/ The Architecture + | |_ debug/ The build type + | | |_ build/ Intermediate object files + | | |_ firmware/ Target output files + | | |_ lib/ Generated libraries + | | |_ tools/ Generated tools + | |_ release/ + | |_ ... + |_ Host + |_ ... + +Components +---------- + +The purpose of a Component is to encapsulate related elements for +selective inclusion in a project, for easy sharing and re-use: + +- **Shared Library** with associated header files +- **App Code** Source files to be compiled directly into the user’s + project +- **Header files** without any associated source or library +- **Build targets** to perform specific actions, such as flashing + binary data to hardware + +By default, a Component is built into a shared library using any source +files found in the base or ``src`` directories. All Arduino Libraries +are built as Components. Note that the application is also built as a +Component library, but the source directory defaults to ``app`` instead +of ``src``. + +Components are referred to simply by name, defined by the directory in +which it is stored. The Component itself is located by looking in all +the directories listed by ``COMPONENT_SEARCH_DIRS``, which contains a +list of repositories. (Every sub-directory of a repository is considered +to be a Component.) If there are Components with the same name in +different search directories, the first one found will be used. + +Components are customised by providing an optional ``component.mk`` +file. + +You can see details of all Components used in a project using +``make list-components``. Add ``V=1`` to get more details. + +Note that the application itself is also built as a Component, and may +be configured in a similar way to any other Component. + +Library variants +~~~~~~~~~~~~~~~~ + +Libraries can often be built using different option settings, so a +mechanism is required to ensure that libraries (including the +application) are rebuilt if those settings change. This is handled using +*variants*, which modifies the library name using a hash of the settings +values. Each variant gets its own build sub-directory so incremental +building works as usual. + +There are several types of config variable: + ++-------------+-------------+-------------+-------------+-------------+ +| Variable | Cached? | Rebuild | Rebuild | Relink | +| type | | Component? | application | application | +| | | | ? | | ++=============+=============+=============+=============+=============+ +| COMPONENT | Y | Y | Y | Y | ++-------------+-------------+-------------+-------------+-------------+ +| CONFIG | Y | N | Y | Y | ++-------------+-------------+-------------+-------------+-------------+ +| RELINK | Y | N | N | Y | ++-------------+-------------+-------------+-------------+-------------+ +| CACHE | Y | N | N | N | ++-------------+-------------+-------------+-------------+-------------+ +| DEBUG | N | N | N | N | ++-------------+-------------+-------------+-------------+-------------+ + +Variables are usually defined in the context of a Component, in the +component.mk file. All Components see the full configuration during +building, not just their own variables. + +The type of a configuration variable is defined by adding its *name* to +one of the following lists: + +``CONFIG_VARS`` The Application library derives its variant from these +variables. Use this type if the Component doesn’t require a rebuild, but +the application does. + +``COMPONENT_VARS`` A Component library derives its variant from these +variables. Any variable which requires a rebuild of the Component +library itself must be listed. For example, the ``esp-open-lwip`` +Component defines this as ``ENABLE_LWIPDEBUG ENABLE_ESPCONN``. The +default values for these produces +``ENABLE_LWIPDEBUG=0 ENABLE_ESPCONN=0``, which is hashed (using MD5) to +produce ``a46d8c208ee44b1ee06f8e69cfa06773``, which is appended to the +library name. + +``RELINK_VARS`` Code isn’t re-compiled, but libraries are re-linked and +firmware images re-generated if any of these variables are changed. For +example, ``make RBOOT_ROM_0=new-rom-file`` rewrites the firmware image +using the given filename. (Also, as the value is cached, if you then do +``make flashapp`` that same iamge gets flashed.) + +``CACHE_VARS`` These variables have no effect on building, but are +cached. Variables such as ``COM_SPEED_ESPTOOL`` fall into this category. + +``DEBUG_VARS`` are generally for information only, and are not cached +(except for :envvar:`SMING_ARCH` and :envvar:`SMING_RELEASE`). + +Dependencies +~~~~~~~~~~~~ + +``COMPONENT_DEPENDS`` identifies a list of Components upon which this +one depends. These are established as pre-requisites so will trigger a +rebuild. In addition, all dependent ``COMPONENT_VARS`` are (recursively) +used in creation of the library hash. + +For example, the ``axtls-8266`` Component declares ``SSL_DEBUG`` as a +``COMPONENT_VAR``. Because ``Sming`` depends on ``sming-arch``, which in +turn depends on ``axtls-8266``, all of these Components get rebuilt as +different variants when ``SSL_DEBUG`` changes values. The project code +(``App`` Component) also gets rebuilt as it implicitly depends on +``Sming``. + +GIT Submodules +~~~~~~~~~~~~~~ + +Sming uses source code from other repositories. Instead of including +local copies, these are handled using GIT submodules. Where changes are +required, patches may be provided as a diff .patch file and/or set of +files to be added/replaced. Only those submodules necessary for a build +are pulled in, as follows: + +- The submodule is fetched from its remote repository +- If a .patch file exists, it is applied +- Any additional files are copied into the submodule directory +- An empty ``.submodule`` file is created to tells the build system + that the submodule is present and correct. + +The patch file must have the same name as the submodule, with a .patch +extension. It can be located in the submodule’s parent directory: + +:: + + |_ Components/ + |_ custom_heap/ + |_ .component.mk Component definition + |_ umm_malloc.patch Diff patch file + |_ umm_malloc/ Submodule directory + |_ .submodule Created after successful patching + ... + +However, if the Component is itself a submodule, then patch files must +be placed in a ``../.patches`` directory: + +:: + + |_ Libraries/ + |_ .patches/ + | |_ Adafruit_SSD1306.patch Diff patch file + | |_ Adafruit_SSD1306/ + | |_ component.mk This file is added to submodule + |_ Adafruit_SSD1306/ The submodule directory + |_ .submodule Created after successful patching + ... + +This example includes additional files for the submodule. There are some +advantages to this approach: + +1. Don’t need to modify or create .patch +2. Changes to the file are easier to follow than in a .patch +3. **IMPORTANT** Adding a component.mk file in this manner allows the + build system to resolve dependencies before any submodules are + fetched. + +In the above example, the ``component.mk`` file defines a dependency on +the ``Adafruit_GFX`` library, so that will automatically get pulled in +as well. + +Component configuration +~~~~~~~~~~~~~~~~~~~~~~~ + +The ``component.mk`` is parsed twice, first from the top-level makefile +and the second time from the sub-make which does the actual building. A +number of variables are used to define behaviour. + +These values are for reference only and should not be modified. + +``COMPONENT_NAME`` Name of the Component ``COMPONENT_PATH`` Base +directory path for Component, no trailing path separator +``COMPONENT_BUILD_DIR`` The current directory. This should be used if +the Component provides any application code or targets to ensure it is +built in the correct directory (but not by this makefile). +``COMPONENT_LIBDIR`` Location to store created Component (shared) +libraries ``COMPONENT_VARIANT`` Name of the library to build +``COMPONENT_LIBPATH`` Full path to the library to be built + +These values may be used to customise Component behaviour and may be +changed as required. + +``COMPONENT_LIBNAME`` By default, the library has the same name as the +Component but can be changed if required. Note that this will be used as +the stem for any variants. Set ``COMPONENT_LIBNAME :=`` if the Component +doesn’t create a library. If you don’t do this, a default library will +be built but will be empty if no source files are found. + +``COMPONENT_TARGETS`` Set this to any additional targets to be built as +part of the Component, prefixed with ``$(COMPONENT_RULE)``. If targets +should be built for each application, use ``CUSTOM_TARGETS`` instead. +See ``spiffs`` for an example. + +``COMPONENT_RULE`` This is a special value used to prefix any custom +targets which are to be built as part of the Component. The target must +be prefixed by ``$(COMPONENT_RULE)`` without any space between it and +the target. This ensures the rule only gets invoked during a component +build, and is ignored by the top-level make. + +``COMPONENT_SUBMODULES`` Relative paths to dependent submodule +directories for this Component. These will be fetched/patched +automatically before building. + +``COMPONENT_SRCDIRS`` Locations for source code relative to +COMPONENT_PATH (defaults to “. src”) + +``COMPONENT_INCDIRS`` Include directories available when building ALL +Components (not just this one). Paths may be relative or absolute. + +``INCDIR`` The resultant set of include directories used to build this +Component. Will contain include directories specified by all other +Components in the build. May be overridden if required. + +``COMPONENT_APPCODE`` List of directories containing source code to be +compiled directly with the application. (Ignore in the project.mk file - +use ``COMPONENT_SRCDIRS`` instead). + +``CUSTOM_BUILD`` Set to 1 if providing an alternative build method. See +`Custom building <#custom-building>`__ section. + +``EXTRA_OBJ`` Absolute paths to any additional binary object files to be +added to the Component archive library. + +``COMPONENT_DEPENDS`` Set to the name(s) of any dependent Components. + +``EXTRA_LIBS`` Set to names of any additional libraries to be linked. + +``EXTRA_LDFLAGS`` Set to any additional flags to be used when linking. + +These values are global so must only be appended to (with ``+=``) , +never overwritten. + +``CUSTOM_TARGETS`` Identifies targets to be built along with the +application. These will be invoked directly by the top-level make. + +``GLOBAL_CFLAGS`` Use only if you need to provide additional compiler +flags to be included when building all Components (including +Application) and custom targets. + +``APP_CFLAGS`` Used when building application and custom targets. + +**IMPORTANT NOTE** + +During initial parsing, many of these variables (specifically, the +``COMPONENT_xxx`` ones) *do not* keep their values. For this reason it +is usually best to use simple variable assignment using ``:=``. + +For example, in ``Esp8266/Components/gdbstub`` we define +``GDB_CMDLINE``. It may be tempting to do this: + +:: + + GDB_CMDLINE = trap '' INT; $(GDB) -x $(COMPONENT_PATH)/gdbcmds -b $(COM_SPEED_GDB) -ex "target remote $(COM_PORT_GDB)" + +That won’t work! By the time ``GDB_CMDLINE`` gets expanded, +``COMPONENT_PATH`` could contain anything. We need ``GDB_CMDLINE`` to be +expanded only when used, so the solution is to take a simple copy of +``COMPONENT_PATH`` and use it instead, like this: + +:: + + GDBSTUB_DIR := $(COMPONENT_PATH) + GDB_CMDLINE = trap '' INT; $(GDB) -x $(GDBSTUB_DIR)/gdbcmds -b $(COM_SPEED_GDB) -ex "target remote $(COM_PORT_GDB)" + +Building +~~~~~~~~ + +For faster builds use make with the ``-j`` (jobs) feature of make. It is +usually necessary to specify a limit for the number of jobs, especially +on virtual machines. There is usually no point in using a figure greater +than (CPU cores + 1). The CI builds use ``-j3``. + +Note that ``Makefile-app.mk`` enforces sequential building to ensure +submodules are fetched and patched correctly. This also ensures that +only one Component is built at a time which keeps the build logs quite +clean and easy to follow. + +Components can be rebuilt and cleaned individually. For example: + +- ``make spiffs-build`` runs the Component ‘make’ for spiffs, which + contains the spiffs library and spiffy tool. +- ``make spiffs-clean`` removes all intermediate build files for the + Component +- ``make spiffs-rebuild`` cleans and then re-builds the Component + +By default, a regular ``make`` performs an incremental build on the +application, which invokes a separate (recursive) make for the ``App`` +Component. All other Components only get built if any of their targets +don’t exist (e.g. variant library not yet built). This makes application +building faster and less ‘busy’, which is generally preferable for +regular application development. For Component development this +behaviour can be changed using the ``FULL_COMPONENT_BUILD`` variable +(which is cached). Examples: + +- ``make FULL_COMPONENT_BUILD=lwip`` will perform an incremental build + on the ``lwip`` Component +- ``make FULL_COMPONENT_BUILD=1`` will incrementally build all + Components + +Custom Building +~~~~~~~~~~~~~~~ + +To use an external makefile or other build system (such as CMake) to +create the Component library, or to add additional shared libraries or +other targets, customise the ``component.mk`` file as follows: + +1. Set ``CUSTOM_BUILD=1`` +2. Define the custom rule, prefixed with ``$(COMPONENT_RULE)``. Note + that Components are built using a separate make instance with the + current directory set to the build output directory, not the source + directory. + +It is important that the rule uses the provided values for +``COMPONENT_LIBNAME``, ``COMPONENT_LIBPATH`` and ``COMPONENT_LIBDIR`` so +that variant building, cleaning, etc. work correctly. See below under +‘Building’, and the Host ``lwip`` Component for an example. + +Components are built using a make instance with the current directory +set to the build output directory, not the source directory. If any +custom building is done then these variables must be obeyed to ensure +variants, etc. work as expected: + +``COMPONENT_LIBNAME`` as provided by component.mk, defaults to component +name, e.g. \ ``Sming`` ``COMPONENT_LIBHASH`` hash of the component +variables used to create unique library names, +e.g. \ ``13cd2ddef79fda79dae1644a33bf48bb`` ``COMPONENT_VARIANT`` name +of the library to be built, including hash. +e.g. \ ``Sming-13cd2ddef79fda79dae1644a33bf48bb`` ``COMPONENT_LIBDIR`` +directory where any generated libraries must be output, +e.g. \ ``/home/user/sming/Sming/out/Esp8266/debug/lib/`` +``COMPONENT_LIBPATH`` full path to the library to be created, +e.g. \ ``/home/user/sming/Sming/out/Esp8266/debug/lib/clib-Sming-13cd2ddef79fda79dae1644a33bf48bb.a`` +``COMPONENT_BUILDDIR`` where to write intermediate object files, +e.g. \ ``/home/user/sming/Sming/out/Esp8266/debug/build/Sming/Sming-13cd2ddef79fda79dae1644a33bf48bb`` + +Porting existing libraries +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +to be completed + +Known Issues +------------ + +**Cleaning** Components are not cleaned unless defined. +e.g. \ ``make axtls-8266-clean`` will fail unless you also specify +``ENABLE_SSL=1``. + +**Empty libraries** Components without any source code produce an empty +library. This is because, for simplicity, we don’t want to add a +component.mk to every Arduino library. + +**Empty Component directories** Every sub-directory in the +``COMPONENT_SEARCH_DIRS`` is interpreted as a Component. For example, +``spiffs`` was moved out of Arch/Esp8266/Components but if an empty +directory called ‘spiffs’ still remains then it will be picked up +instead of the main one. These sorts of issues can be checked using +``make list-components`` to ensure the correct Component path has been +selected. + +**Components as submodules** All component.mk files must be available +for parsing. For submodules, it can be provided in a .patch/ +sub-directory. Placing the component.mk file within the submodule itself +is not currently supported. diff --git a/Sming/project.mk b/Sming/project.mk index 5586e87bd6..697cd20cf4 100644 --- a/Sming/project.mk +++ b/Sming/project.mk @@ -15,6 +15,8 @@ endif # Don't bother with implicit checks .SUFFIXES: +.NOTPARALLEL: + .PHONY: all all: checkdirs components application ##(default) Build all Component libraries @@ -155,19 +157,20 @@ CMP_$1_BUILD_BASE := $3/$1 COMPONENT_BUILD_DIR := $$(CMP_$1_BUILD_BASE) COMPONENT_VARS := COMPONENT_TARGETS := +COMPONENT_DEPENDS := EXTRA_LIBS := EXTRA_LDFLAGS := # Process any component.mk file (optional) ifneq (,$(wildcard $2/component.mk)) COMPONENT_PATH := $2 +COMPONENT_LIBPATH := $$(COMPONENT_LIBDIR)/$$(COMPONENT_LIBNAME).a COMPONENT_SUBMODULES := -COMPONENT_DEPENDS := COMPONENT_APPCODE := include $2/component.mk CMP_$1_SUBMODULES := $$(addprefix $2/,$$(COMPONENT_SUBMODULES)) SUBMODULES += $$(CMP_$1_SUBMODULES) -CMP_$1_DEPENDS := $$(COMPONENT_DEPENDS) CMP_$1_VARS := $$(sort $$(COMPONENT_VARS)) +CONFIG_VARS += $$(CMP_$1_VARS) CMP_$1_APPCODE := $$(COMPONENT_APPCODE) LIBS += $$(EXTRA_LIBS) CMP_$1_LDFLAGS := $$(EXTRA_LDFLAGS) @@ -178,16 +181,16 @@ CMP_$1_BUILD_DIR := $$(COMPONENT_BUILD_DIR) CMP_$1_LIBNAME := $$(COMPONENT_LIBNAME) CMP_$1_INCDIRS := $$(COMPONENT_INCDIRS) # Variables including those inherited from dependencies (will be recursively expanded when required) +CMP_$1_DEPENDS := $$(COMPONENT_DEPENDS) CMP_$1_DEPVARS = $$(CMP_$1_VARS) $$(foreach c,$$(CMP_$1_DEPENDS),$$(CMP_$$c_DEPVARS)) -CONFIG_VARS += $$(CMP_$1_VARS) APPCODE += $$(call AbsoluteSourcePath,$2,$$(CMP_$1_APPCODE)) -PARSED_COMPONENTS += $1 COMPONENTS += $$(filter-out $$(COMPONENTS),$$(CMP_$1_DEPENDS)) ifneq (App,$1) COMPONENTS_EXTRA_INCDIR += $$(call AbsoluteSourcePath,$2,$$(CMP_$1_INCDIRS)) # Recursively parse any dependencies DEPENDENCIES := $$(filter-out $$(PARSED_COMPONENTS),$$(CMP_$1_DEPENDS)) ifneq (,$$(DEPENDENCIES)) +PARSED_COMPONENTS += $$(DEPENDENCIES) $$(call ParseComponentList,$$(DEPENDENCIES)) endif endif # App @@ -225,14 +228,13 @@ COMPONENT_SEARCH_DIRS := $(call FixPath,$(COMPONENT_SEARCH_DIRS)) COMPONENTS_EXTRA_INCDIR += $(COMPONENT_SEARCH_DIRS) COMPONENT_SEARCH_DIRS += $(ARCH_COMPONENTS) $(SMING_HOME)/Components $(SMING_HOME)/Libraries +# Perform whole-file patching to ensure submodule component.mk files are present +$(foreach d,$(COMPONENT_SEARCH_DIRS),\ + $(if $(wildcard $d/.patches/*/.),$(shell cd $d && cp -r .patches/*/ .))) + # And add in any requested Arduino libraries COMPONENTS += $(sort $(ARDUINO_LIBRARIES)) -# Each Component search directory can have an optional 'components.mk' file. -# This is primarily for defining dependencies for Arduino Libraries; many of these are submodules, -# so we can establish dependencies without resorting to elaborate recursive fetch/scan strategies. -$(foreach d,$(COMPONENT_SEARCH_DIRS),$(eval -include $d/components.mk)) - # Pull in all Component definitions $(eval $(call ParseComponentList,$(COMPONENTS))) @@ -283,35 +285,6 @@ $(foreach v,$(CONFIG_VARS) $(CACHE_VARS),$(eval export $v)) ##@Building -# Apply patch to a submodule -# $1 -> patch file with relative path -define ApplyPatch - $(GIT) apply -v $1 --ignore-whitespace --whitespace=nowarn -endef - -# If there's a patch for this submodule, apply it -# We look for patch in .. and in ../.patches -# $1 -> submodule path -# $2 -> name of patch file -define TryApplyPatch - cd $1 && if [ -f ../$2 ]; then \ - $(call ApplyPatch,../$2); \ - elif [ -f ../.patches/$2 ]; then \ - $(call ApplyPatch,../.patches/$2); \ - fi -endef - -# Update and patch submodule -# Patch file is either in submodule parent directory itself or subdirectory .patches from there -.NOTPARALLEL: %/.submodule -%/.submodule: - $(info ) - $(info Fetching submodule '$*' ...) - $(Q) cd $*/.. && $(GIT) submodule update --init --force --recursive $(*F) - $(Q) $(call TryApplyPatch,$*,$(*F).patch) - $(Q) touch $@ - - # Define target for building a component library # We add a pseudo-target for each Component (using its name) to (re)build all contained targets # e.g. spiffs: libspiffs.a spiffy.exe @@ -399,11 +372,6 @@ $(BUILD_DIRS) $(FW_BASE) $(TOOLS_BASE) $(APP_LIBDIR) $(USER_LIBDIR): .PHONY: components components: $(SUBMODULES:=/.submodule) $(ALL_COMPONENT_TARGETS) $(CUSTOM_TARGETS) -# Pull in all submodules, regardless of whether they're used or not -.PHONY: all-submodules -all-submodules: $(ALL_SUBMODULES:=/.submodule) ##Fetch all third-party submodules (but do not build) - - ##@Cleaning SMING_MAKE := $(Q) $(MAKE) --no-print-directory -C $(SMING_HOME) diff --git a/docs/.project b/docs/.project new file mode 100644 index 0000000000..c5d77c7f73 --- /dev/null +++ b/docs/.project @@ -0,0 +1,17 @@ + + + sphinx.docs + + + + + + org.python.pydev.PyDevBuilder + + + + + + org.python.pydev.pythonNature + + diff --git a/docs/Doxyfile b/docs/Doxyfile index 254826b17e..2ff79dc752 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -1,124 +1,11 @@ -# Doxyfile 1.8.9.1 - +# # This file describes the settings to be used by the documentation system # doxygen (www.doxygen.org) for a project. # -# All text after a double hash (##) is considered a comment and is placed in -# front of the TAG it is preceding. -# -# All text after a single hash (#) is considered a comment and will be ignored. -# The format is: -# TAG = value [value, ...] -# For lists, items can also be appended using: -# TAG += value [value, ...] -# Values that contain spaces should be placed between quotes (\" \"). - -#--------------------------------------------------------------------------- -# Project related configuration options -#--------------------------------------------------------------------------- - -# This tag specifies the encoding used for all characters in the config file -# that follow. The default is UTF-8 which is also the encoding used for all text -# before the first occurrence of this tag. Doxygen uses libiconv (or the iconv -# built into libc) for the transcoding. See http://www.gnu.org/software/libiconv -# for the list of possible encodings. -# The default value is: UTF-8. - -DOXYFILE_ENCODING = UTF-8 - -# The PROJECT_NAME tag is a single word (or a sequence of words surrounded by -# double-quotes, unless you are using Doxywizard) that should identify the -# project for which the documentation is generated. This name is used in the -# title of most generated pages and in a few other places. -# The default value is: My Project. PROJECT_NAME = "Sming Framework API" - -# The PROJECT_NUMBER tag can be used to enter a project or revision number. This -# could be handy for archiving the generated documentation or if some version -# control system is used. - -PROJECT_NUMBER = - -# Using the PROJECT_BRIEF tag one can provide an optional one line description -# for a project that appears at the top of each page and should give viewer a -# quick idea about the purpose of the project. Keep the description short. - PROJECT_BRIEF = "Sming - Open Source framework for high efficiency WiFi SoC ESP8266 native development with C++ language." - -# With the PROJECT_LOGO tag one can specify a logo or an icon that is included -# in the documentation. The maximum height of the logo should not exceed 55 -# pixels and the maximum width should not exceed 200 pixels. Doxygen will copy -# the logo to the output directory. - -PROJECT_LOGO = - -# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path -# into which the generated documentation will be written. If a relative path is -# entered, it will be relative to the location where doxygen was started. If -# left blank the current directory will be used. - -OUTPUT_DIRECTORY = api - -# If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub- -# directories (in 2 levels) under the output directory of each output format and -# will distribute the generated files over these directories. Enabling this -# option can be useful when feeding doxygen a huge amount of source files, where -# putting all generated files in the same directory would otherwise causes -# performance problems for the file system. -# The default value is: NO. - -CREATE_SUBDIRS = NO - -# If the ALLOW_UNICODE_NAMES tag is set to YES, doxygen will allow non-ASCII -# characters to appear in the names of generated files. If set to NO, non-ASCII -# characters will be escaped, for example _xE3_x81_x84 will be used for Unicode -# U+3044. -# The default value is: NO. - -ALLOW_UNICODE_NAMES = NO - -# The OUTPUT_LANGUAGE tag is used to specify the language in which all -# documentation generated by doxygen is written. Doxygen will use this -# information to generate all constant output in the proper language. -# Possible values are: Afrikaans, Arabic, Armenian, Brazilian, Catalan, Chinese, -# Chinese-Traditional, Croatian, Czech, Danish, Dutch, English (United States), -# Esperanto, Farsi (Persian), Finnish, French, German, Greek, Hungarian, -# Indonesian, Italian, Japanese, Japanese-en (Japanese with English messages), -# Korean, Korean-en (Korean with English messages), Latvian, Lithuanian, -# Macedonian, Norwegian, Persian (Farsi), Polish, Portuguese, Romanian, Russian, -# Serbian, Serbian-Cyrillic, Slovak, Slovene, Spanish, Swedish, Turkish, -# Ukrainian and Vietnamese. -# The default value is: English. - -OUTPUT_LANGUAGE = English - -# If the BRIEF_MEMBER_DESC tag is set to YES, doxygen will include brief member -# descriptions after the members that are listed in the file and class -# documentation (similar to Javadoc). Set to NO to disable this. -# The default value is: YES. - -BRIEF_MEMBER_DESC = YES - -# If the REPEAT_BRIEF tag is set to YES, doxygen will prepend the brief -# description of a member or function before the detailed description -# -# Note: If both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the -# brief descriptions will be completely suppressed. -# The default value is: YES. - -REPEAT_BRIEF = YES - -# This tag implements a quasi-intelligent brief description abbreviator that is -# used to form the text in various listings. Each string in this list, if found -# as the leading text of the brief description, will be stripped from the text -# and the result, after processing the whole list, is used as the annotated -# text. Otherwise, the brief description is used as-is. If left blank, the -# following values are used ($name is automatically replaced with the name of -# the entity):The $name class, The $name widget, The $name file, is, provides, -# specifies, contains, represents, a, an and the. - -ABBREVIATE_BRIEF = +OUTPUT_DIRECTORY = api # If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then # doxygen will generate a detailed section even if there is only a brief @@ -142,76 +29,6 @@ INLINE_INHERITED_MEMB = YES FULL_PATH_NAMES = NO -# The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path. -# Stripping is only done if one of the specified strings matches the left-hand -# part of the path. The tag can be used to show relative paths in the file list. -# If left blank the directory from which doxygen is run is used as the path to -# strip. -# -# Note that you can specify absolute paths here, but also relative paths, which -# will be relative from the directory where doxygen is started. -# This tag requires that the tag FULL_PATH_NAMES is set to YES. - -STRIP_FROM_PATH = - -# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the -# path mentioned in the documentation of a class, which tells the reader which -# header file to include in order to use a class. If left blank only the name of -# the header file containing the class definition is used. Otherwise one should -# specify the list of include paths that are normally passed to the compiler -# using the -I flag. - -STRIP_FROM_INC_PATH = - -# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but -# less readable) file names. This can be useful is your file systems doesn't -# support long names like on DOS, Mac, or CD-ROM. -# The default value is: NO. - -SHORT_NAMES = NO - -# If the JAVADOC_AUTOBRIEF tag is set to YES then doxygen will interpret the -# first line (until the first dot) of a Javadoc-style comment as the brief -# description. If set to NO, the Javadoc-style will behave just like regular Qt- -# style comments (thus requiring an explicit @brief command for a brief -# description.) -# The default value is: NO. - -JAVADOC_AUTOBRIEF = NO - -# If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first -# line (until the first dot) of a Qt-style comment as the brief description. If -# set to NO, the Qt-style will behave just like regular Qt-style comments (thus -# requiring an explicit \brief command for a brief description.) -# The default value is: NO. - -QT_AUTOBRIEF = NO - -# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make doxygen treat a -# multi-line C++ special comment block (i.e. a block of //! or /// comments) as -# a brief description. This used to be the default behavior. The new default is -# to treat a multi-line C++ comment block as a detailed description. Set this -# tag to YES if you prefer the old behavior instead. -# -# Note that setting this tag to YES also means that rational rose comments are -# not recognized any more. -# The default value is: NO. - -MULTILINE_CPP_IS_BRIEF = NO - -# If the INHERIT_DOCS tag is set to YES then an undocumented member inherits the -# documentation from any documented member that it re-implements. -# The default value is: YES. - -INHERIT_DOCS = YES - -# If the SEPARATE_MEMBER_PAGES tag is set to YES then doxygen will produce a new -# page for each member. If set to NO, the documentation of a member will be part -# of the file/class/namespace that contains it. -# The default value is: NO. - -SEPARATE_MEMBER_PAGES = NO - # The TAB_SIZE tag can be used to set the number of spaces in a tab. Doxygen # uses this value to replace tabs by spaces in code fragments. # Minimum value: 1, maximum value: 16, default value: 4. @@ -230,342 +47,14 @@ TAB_SIZE = 4 ALIASES = "license=@par License:\n" -# This tag can be used to specify a number of word-keyword mappings (TCL only). -# A mapping has the form "name=value". For example adding "class=itcl::class" -# will allow you to use the command class in the itcl::class meaning. - -TCL_SUBST = - -# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources -# only. Doxygen will then generate output that is more tailored for C. For -# instance, some of the names that are used will be different. The list of all -# members will be omitted, etc. -# The default value is: NO. - -OPTIMIZE_OUTPUT_FOR_C = NO - -# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or -# Python sources only. Doxygen will then generate output that is more tailored -# for that language. For instance, namespaces will be presented as packages, -# qualified scopes will look different, etc. -# The default value is: NO. - -OPTIMIZE_OUTPUT_JAVA = NO - -# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran -# sources. Doxygen will then generate output that is tailored for Fortran. -# The default value is: NO. - -OPTIMIZE_FOR_FORTRAN = NO - -# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL -# sources. Doxygen will then generate output that is tailored for VHDL. -# The default value is: NO. - -OPTIMIZE_OUTPUT_VHDL = NO - -# Doxygen selects the parser to use depending on the extension of the files it -# parses. With this tag you can assign which parser to use for a given -# extension. Doxygen has a built-in mapping, but you can override or extend it -# using this tag. The format is ext=language, where ext is a file extension, and -# language is one of the parsers supported by doxygen: IDL, Java, Javascript, -# C#, C, C++, D, PHP, Objective-C, Python, Fortran (fixed format Fortran: -# FortranFixed, free formatted Fortran: FortranFree, unknown formatted Fortran: -# Fortran. In the later case the parser tries to guess whether the code is fixed -# or free formatted code, this is the default for Fortran type files), VHDL. For -# instance to make doxygen treat .inc files as Fortran files (default is PHP), -# and .f files as C (default is Fortran), use: inc=Fortran f=C. -# -# Note: For files without extension you can use no_extension as a placeholder. -# -# Note that for custom extensions you also need to set FILE_PATTERNS otherwise -# the files are not read by doxygen. - -EXTENSION_MAPPING = - -# If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments -# according to the Markdown format, which allows for more readable -# documentation. See http://daringfireball.net/projects/markdown/ for details. -# The output of markdown processing is further processed by doxygen, so you can -# mix doxygen, HTML, and XML commands with Markdown formatting. Disable only in -# case of backward compatibilities issues. -# The default value is: YES. - -MARKDOWN_SUPPORT = YES - -# When enabled doxygen tries to link words that correspond to documented -# classes, or namespaces to their corresponding documentation. Such a link can -# be prevented in individual cases by putting a % sign in front of the word or -# globally by setting AUTOLINK_SUPPORT to NO. -# The default value is: YES. - -AUTOLINK_SUPPORT = YES - -# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want -# to include (a tag file for) the STL sources as input, then you should set this -# tag to YES in order to let doxygen match functions declarations and -# definitions whose arguments contain STL classes (e.g. func(std::string); -# versus func(std::string) {}). This also make the inheritance and collaboration -# diagrams that involve STL classes more complete and accurate. -# The default value is: NO. - -BUILTIN_STL_SUPPORT = NO - -# If you use Microsoft's C++/CLI language, you should set this option to YES to -# enable parsing support. -# The default value is: NO. - -CPP_CLI_SUPPORT = NO - -# Set the SIP_SUPPORT tag to YES if your project consists of sip (see: -# http://www.riverbankcomputing.co.uk/software/sip/intro) sources only. Doxygen -# will parse them like normal C++ but will assume all classes use public instead -# of private inheritance when no explicit protection keyword is present. -# The default value is: NO. - -SIP_SUPPORT = NO - -# For Microsoft's IDL there are propget and propput attributes to indicate -# getter and setter methods for a property. Setting this option to YES will make -# doxygen to replace the get and set methods by a property in the documentation. -# This will only work if the methods are indeed getting or setting a simple -# type. If this is not the case, or you want to show the methods anyway, you -# should set this option to NO. -# The default value is: YES. - -IDL_PROPERTY_SUPPORT = YES - -# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC -# tag is set to YES then doxygen will reuse the documentation of the first -# member in the group (if any) for the other members of the group. By default -# all members of a group must be documented explicitly. -# The default value is: NO. - -DISTRIBUTE_GROUP_DOC = NO - -# Set the SUBGROUPING tag to YES to allow class member groups of the same type -# (for instance a group of public functions) to be put as a subgroup of that -# type (e.g. under the Public Functions section). Set it to NO to prevent -# subgrouping. Alternatively, this can be done per class using the -# \nosubgrouping command. -# The default value is: YES. - -SUBGROUPING = YES - -# When the INLINE_GROUPED_CLASSES tag is set to YES, classes, structs and unions -# are shown inside the group in which they are included (e.g. using \ingroup) -# instead of on a separate page (for HTML and Man pages) or section (for LaTeX -# and RTF). -# -# Note that this feature does not work in combination with -# SEPARATE_MEMBER_PAGES. -# The default value is: NO. - -INLINE_GROUPED_CLASSES = NO - -# When the INLINE_SIMPLE_STRUCTS tag is set to YES, structs, classes, and unions -# with only public data fields or simple typedef fields will be shown inline in -# the documentation of the scope in which they are defined (i.e. file, -# namespace, or group documentation), provided this scope is documented. If set -# to NO, structs, classes, and unions are shown on a separate page (for HTML and -# Man pages) or section (for LaTeX and RTF). -# The default value is: NO. - -INLINE_SIMPLE_STRUCTS = NO - -# When TYPEDEF_HIDES_STRUCT tag is enabled, a typedef of a struct, union, or -# enum is documented as struct, union, or enum with the name of the typedef. So -# typedef struct TypeS {} TypeT, will appear in the documentation as a struct -# with name TypeT. When disabled the typedef will appear as a member of a file, -# namespace, or class. And the struct will be named TypeS. This can typically be -# useful for C code in case the coding convention dictates that all compound -# types are typedef'ed and only the typedef is referenced, never the tag name. -# The default value is: NO. - -TYPEDEF_HIDES_STRUCT = NO - -# The size of the symbol lookup cache can be set using LOOKUP_CACHE_SIZE. This -# cache is used to resolve symbols given their name and scope. Since this can be -# an expensive process and often the same symbol appears multiple times in the -# code, doxygen keeps a cache of pre-resolved symbols. If the cache is too small -# doxygen will become slower. If the cache is too large, memory is wasted. The -# cache size is given by this formula: 2^(16+LOOKUP_CACHE_SIZE). The valid range -# is 0..9, the default is 0, corresponding to a cache size of 2^16=65536 -# symbols. At the end of a run doxygen will report the cache usage and suggest -# the optimal cache size from a speed point of view. -# Minimum value: 0, maximum value: 9, default value: 0. - -LOOKUP_CACHE_SIZE = 0 - -#--------------------------------------------------------------------------- -# Build related configuration options -#--------------------------------------------------------------------------- - -# If the EXTRACT_ALL tag is set to YES, doxygen will assume all entities in -# documentation are documented, even if no documentation was available. Private -# class members and static file members will be hidden unless the -# EXTRACT_PRIVATE respectively EXTRACT_STATIC tags are set to YES. -# Note: This will also disable the warnings about undocumented members that are -# normally produced when WARNINGS is set to YES. -# The default value is: NO. - -EXTRACT_ALL = NO - -# If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will -# be included in the documentation. -# The default value is: NO. - -EXTRACT_PRIVATE = NO - -# If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal -# scope will be included in the documentation. -# The default value is: NO. - -EXTRACT_PACKAGE = NO - # If the EXTRACT_STATIC tag is set to YES, all static members of a file will be # included in the documentation. # The default value is: NO. EXTRACT_STATIC = YES -# If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined -# locally in source files will be included in the documentation. If set to NO, -# only classes defined in header files are included. Does not have any effect -# for Java sources. -# The default value is: YES. - -EXTRACT_LOCAL_CLASSES = YES - -# This flag is only useful for Objective-C code. If set to YES, local methods, -# which are defined in the implementation section but not in the interface are -# included in the documentation. If set to NO, only methods in the interface are -# included. -# The default value is: NO. - -EXTRACT_LOCAL_METHODS = NO - -# If this flag is set to YES, the members of anonymous namespaces will be -# extracted and appear in the documentation as a namespace called -# 'anonymous_namespace{file}', where file will be replaced with the base name of -# the file that contains the anonymous namespace. By default anonymous namespace -# are hidden. -# The default value is: NO. - -EXTRACT_ANON_NSPACES = NO - -# If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all -# undocumented members inside documented classes or files. If set to NO these -# members will be included in the various overviews, but no documentation -# section is generated. This option has no effect if EXTRACT_ALL is enabled. -# The default value is: NO. - -HIDE_UNDOC_MEMBERS = NO - -# If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all -# undocumented classes that are normally visible in the class hierarchy. If set -# to NO, these classes will be included in the various overviews. This option -# has no effect if EXTRACT_ALL is enabled. -# The default value is: NO. - -HIDE_UNDOC_CLASSES = NO - -# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend -# (class|struct|union) declarations. If set to NO, these declarations will be -# included in the documentation. -# The default value is: NO. - -HIDE_FRIEND_COMPOUNDS = NO - -# If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any -# documentation blocks found inside the body of a function. If set to NO, these -# blocks will be appended to the function's detailed documentation block. -# The default value is: NO. - -HIDE_IN_BODY_DOCS = NO - -# The INTERNAL_DOCS tag determines if documentation that is typed after a -# \internal command is included. If the tag is set to NO then the documentation -# will be excluded. Set it to YES to include the internal documentation. -# The default value is: NO. - -INTERNAL_DOCS = NO - -# If the CASE_SENSE_NAMES tag is set to NO then doxygen will only generate file -# names in lower-case letters. If set to YES, upper-case letters are also -# allowed. This is useful if you have classes or files whose names only differ -# in case and if your file system supports case sensitive file names. Windows -# and Mac users are advised to set this option to NO. -# The default value is: system dependent. - CASE_SENSE_NAMES = YES -# If the HIDE_SCOPE_NAMES tag is set to NO then doxygen will show members with -# their full class and namespace scopes in the documentation. If set to YES, the -# scope will be hidden. -# The default value is: NO. - -HIDE_SCOPE_NAMES = NO - -# If the HIDE_COMPOUND_REFERENCE tag is set to NO (default) then doxygen will -# append additional text to a page's title, such as Class Reference. If set to -# YES the compound reference will be hidden. -# The default value is: NO. - -HIDE_COMPOUND_REFERENCE= NO - -# If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of -# the files that are included by a file in the documentation of that file. -# The default value is: YES. - -SHOW_INCLUDE_FILES = YES - -# If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each -# grouped member an include statement to the documentation, telling the reader -# which file to include in order to use the member. -# The default value is: NO. - -SHOW_GROUPED_MEMB_INC = NO - -# If the FORCE_LOCAL_INCLUDES tag is set to YES then doxygen will list include -# files with double quotes in the documentation rather than with sharp brackets. -# The default value is: NO. - -FORCE_LOCAL_INCLUDES = NO - -# If the INLINE_INFO tag is set to YES then a tag [inline] is inserted in the -# documentation for inline members. -# The default value is: YES. - -INLINE_INFO = YES - -# If the SORT_MEMBER_DOCS tag is set to YES then doxygen will sort the -# (detailed) documentation of file and class members alphabetically by member -# name. If set to NO, the members will appear in declaration order. -# The default value is: YES. - -SORT_MEMBER_DOCS = YES - -# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief -# descriptions of file, namespace and class members alphabetically by member -# name. If set to NO, the members will appear in declaration order. Note that -# this will also influence the order of the classes in the class list. -# The default value is: NO. - -SORT_BRIEF_DOCS = NO - -# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the -# (brief and detailed) documentation of class members so that constructors and -# destructors are listed first. If set to NO the constructors will appear in the -# respective orders defined by SORT_BRIEF_DOCS and SORT_MEMBER_DOCS. -# Note: If SORT_BRIEF_DOCS is set to NO this option is ignored for sorting brief -# member documentation. -# Note: If SORT_MEMBER_DOCS is set to NO this option is ignored for sorting -# detailed member documentation. -# The default value is: NO. - -SORT_MEMBERS_CTORS_1ST = NO - # If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy # of group names into alphabetical order. If set to NO the group names will # appear in their defined order. @@ -573,68 +62,6 @@ SORT_MEMBERS_CTORS_1ST = NO SORT_GROUP_NAMES = YES -# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by -# fully-qualified names, including namespaces. If set to NO, the class list will -# be sorted only by class name, not including the namespace part. -# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. -# Note: This option applies only to the class list, not to the alphabetical -# list. -# The default value is: NO. - -SORT_BY_SCOPE_NAME = NO - -# If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to do proper -# type resolution of all parameters of a function it will reject a match between -# the prototype and the implementation of a member function even if there is -# only one candidate or it is obvious which candidate to choose by doing a -# simple string match. By disabling STRICT_PROTO_MATCHING doxygen will still -# accept a match between prototype and implementation in such cases. -# The default value is: NO. - -STRICT_PROTO_MATCHING = NO - -# The GENERATE_TODOLIST tag can be used to enable (YES) or disable (NO) the todo -# list. This list is created by putting \todo commands in the documentation. -# The default value is: YES. - -GENERATE_TODOLIST = YES - -# The GENERATE_TESTLIST tag can be used to enable (YES) or disable (NO) the test -# list. This list is created by putting \test commands in the documentation. -# The default value is: YES. - -GENERATE_TESTLIST = YES - -# The GENERATE_BUGLIST tag can be used to enable (YES) or disable (NO) the bug -# list. This list is created by putting \bug commands in the documentation. -# The default value is: YES. - -GENERATE_BUGLIST = YES - -# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or disable (NO) -# the deprecated list. This list is created by putting \deprecated commands in -# the documentation. -# The default value is: YES. - -GENERATE_DEPRECATEDLIST= YES - -# The ENABLED_SECTIONS tag can be used to enable conditional documentation -# sections, marked by \if ... \endif and \cond -# ... \endcond blocks. - -ENABLED_SECTIONS = - -# The MAX_INITIALIZER_LINES tag determines the maximum number of lines that the -# initial value of a variable or macro / define can have for it to appear in the -# documentation. If the initializer consists of more lines than specified here -# it will be hidden. Use a value of 0 to hide initializers completely. The -# appearance of the value of individual variables and macros / defines can be -# controlled using \showinitializer or \hideinitializer command in the -# documentation regardless of this setting. -# Minimum value: 0, maximum value: 10000, default value: 30. - -MAX_INITIALIZER_LINES = 30 - # Set the SHOW_USED_FILES tag to NO to disable the list of files generated at # the bottom of the documentation of classes and structs. If set to YES, the # list will mention the files that were used to generate the documentation. @@ -649,99 +76,6 @@ SHOW_USED_FILES = NO SHOW_FILES = NO -# Set the SHOW_NAMESPACES tag to NO to disable the generation of the Namespaces -# page. This will remove the Namespaces entry from the Quick Index and from the -# Folder Tree View (if specified). -# The default value is: YES. - -SHOW_NAMESPACES = YES - -# The FILE_VERSION_FILTER tag can be used to specify a program or script that -# doxygen should invoke to get the current version for each file (typically from -# the version control system). Doxygen will invoke the program by executing (via -# popen()) the command command input-file, where command is the value of the -# FILE_VERSION_FILTER tag, and input-file is the name of an input file provided -# by doxygen. Whatever the program writes to standard output is used as the file -# version. For an example see the documentation. - -FILE_VERSION_FILTER = - -# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed -# by doxygen. The layout file controls the global structure of the generated -# output files in an output format independent way. To create the layout file -# that represents doxygen's defaults, run doxygen with the -l option. You can -# optionally specify a file name after the option, if omitted DoxygenLayout.xml -# will be used as the name of the layout file. -# -# Note that if you run doxygen from a directory containing a file called -# DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE -# tag is left empty. - -LAYOUT_FILE = - -# The CITE_BIB_FILES tag can be used to specify one or more bib files containing -# the reference definitions. This must be a list of .bib files. The .bib -# extension is automatically appended if omitted. This requires the bibtex tool -# to be installed. See also http://en.wikipedia.org/wiki/BibTeX for more info. -# For LaTeX the style of the bibliography can be controlled using -# LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the -# search path. See also \cite for info how to create references. - -CITE_BIB_FILES = - -#--------------------------------------------------------------------------- -# Configuration options related to warning and progress messages -#--------------------------------------------------------------------------- - -# The QUIET tag can be used to turn on/off the messages that are generated to -# standard output by doxygen. If QUIET is set to YES this implies that the -# messages are off. -# The default value is: NO. - -QUIET = NO - -# The WARNINGS tag can be used to turn on/off the warning messages that are -# generated to standard error (stderr) by doxygen. If WARNINGS is set to YES -# this implies that the warnings are on. -# -# Tip: Turn warnings on while writing the documentation. -# The default value is: YES. - -WARNINGS = YES - -# If the WARN_IF_UNDOCUMENTED tag is set to YES then doxygen will generate -# warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag -# will automatically be disabled. -# The default value is: YES. - -WARN_IF_UNDOCUMENTED = YES - -# If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for -# potential errors in the documentation, such as not documenting some parameters -# in a documented function, or documenting parameters that don't exist or using -# markup commands wrongly. -# The default value is: YES. - -WARN_IF_DOC_ERROR = YES - -# This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that -# are documented, but have no documentation for their parameters or return -# value. If set to NO, doxygen will only warn about wrong or incomplete -# parameter documentation, but not about the absence of documentation. -# The default value is: NO. - -WARN_NO_PARAMDOC = NO - -# The WARN_FORMAT tag determines the format of the warning messages that doxygen -# can produce. The string should contain the $file, $line, and $text tags, which -# will be replaced by the file and line number from which the warning originated -# and the warning text. Optionally the format may contain $version, which will -# be replaced by the version of the file (if it could be obtained via -# FILE_VERSION_FILTER) -# The default value is: $file:$line: $text. - -WARN_FORMAT = "$file:$line: $text" - # The WARN_LOGFILE tag can be used to specify a file to which warning and error # messages should be written. If left blank the output is written to standard # error (stderr). @@ -758,25 +92,24 @@ WARN_LOGFILE = api/error.log # spaces. # Note: If this tag is empty the current directory is searched. -INPUT = api.dox sdk.dox \ - ../Sming/Core \ - ../Sming/Platform \ - ../Sming/Services \ - ../Sming/Wiring \ - ../Sming/Components/rboot \ - ../Sming/Libraries \ - $(ESP_HOME)/sdk/include/gpio.h \ - ../Sming/System \ - ../Sming/Components/gdbstub \ - -# This tag can be used to specify the character encoding of the source files -# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses -# libiconv (or the iconv built into libc) for the transcoding. See the libiconv -# documentation (see: http://www.gnu.org/software/libiconv) for the list of -# possible encodings. -# The default value is: UTF-8. - -INPUT_ENCODING = UTF-8 +INPUT = \ + ../Sming/Core \ + ../Sming/Platform \ + ../Sming/Services \ + ../Sming/Wiring \ + ../Sming/Libraries/ArduinoJson6/include \ + $(ESP_HOME)/sdk/include/gpio.h \ + ../Sming/System \ + ../Sming/Arch/Esp8266/Components/spi_flash \ + ../Sming/Arch/Esp8266/Components/rboot \ + ../Sming/Arch/Esp8266/Components/gdbstub + +INCLUDE_PATH = \ + ../Sming/Core + +INPUT_ENCODING = ISO-8859-1 + +RECURSIVE = YES # If the value of the INPUT tag contains directories, you can use the # FILE_PATTERNS tag to specify one or more wildcard patterns (like *.cpp and @@ -789,12 +122,6 @@ INPUT_ENCODING = UTF-8 FILE_PATTERNS = *.h -# The RECURSIVE tag can be used to specify whether or not subdirectories should -# be searched for input files as well. -# The default value is: NO. - -RECURSIVE = YES - # The EXCLUDE tag can be used to specify files and/or directories that should be # excluded from the INPUT source files. This way you can easily exclude a # subdirectory from a directory tree whose root is specified with the INPUT tag. @@ -804,13 +131,6 @@ RECURSIVE = YES EXCLUDE = samples Sming/Libraries -# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or -# directories that are symbolic links (a Unix file system feature) are excluded -# from the input. -# The default value is: NO. - -EXCLUDE_SYMLINKS = NO - # If the value of the INPUT tag contains directories, you can use the # EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude # certain files from those directories. @@ -857,54 +177,6 @@ EXAMPLE_RECURSIVE = YES IMAGE_PATH = -# The INPUT_FILTER tag can be used to specify a program that doxygen should -# invoke to filter for each input file. Doxygen will invoke the filter program -# by executing (via popen()) the command: -# -# -# -# where is the value of the INPUT_FILTER tag, and is the -# name of an input file. Doxygen will then use the output that the filter -# program writes to standard output. If FILTER_PATTERNS is specified, this tag -# will be ignored. -# -# Note that the filter must not add or remove lines; it is applied before the -# code is scanned, but not when the output code is generated. If lines are added -# or removed, the anchors will not be placed correctly. - -INPUT_FILTER = - -# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern -# basis. Doxygen will compare the file name with each pattern and apply the -# filter if there is a match. The filters are a list of the form: pattern=filter -# (like *.cpp=my_cpp_filter). See INPUT_FILTER for further information on how -# filters are used. If the FILTER_PATTERNS tag is empty or if none of the -# patterns match the file name, INPUT_FILTER is applied. - -FILTER_PATTERNS = - -# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using -# INPUT_FILTER) will also be used to filter the input files that are used for -# producing the source files to browse (i.e. when SOURCE_BROWSER is set to YES). -# The default value is: NO. - -FILTER_SOURCE_FILES = NO - -# The FILTER_SOURCE_PATTERNS tag can be used to specify source filters per file -# pattern. A pattern will override the setting for FILTER_PATTERN (if any) and -# it is also possible to disable source filtering for a specific pattern using -# *.ext= (so without naming a filter). -# This tag requires that the tag FILTER_SOURCE_FILES is set to YES. - -FILTER_SOURCE_PATTERNS = - -# If the USE_MDFILE_AS_MAINPAGE tag refers to the name of a markdown file that -# is part of the input, its contents will be placed on the main page -# (index.html). This can be useful if you have a project on for instance GitHub -# and want to reuse the introduction page also for the doxygen output. - -USE_MDFILE_AS_MAINPAGE = - #--------------------------------------------------------------------------- # Configuration options related to source browsing #--------------------------------------------------------------------------- @@ -1036,834 +308,16 @@ COLS_IN_ALPHA_INDEX = 5 IGNORE_PREFIX = -#--------------------------------------------------------------------------- -# Configuration options related to the HTML output -#--------------------------------------------------------------------------- - -# If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output -# The default value is: YES. - -GENERATE_HTML = YES - -# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a -# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of -# it. -# The default directory is: html. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_OUTPUT = "sming" - -# The HTML_FILE_EXTENSION tag can be used to specify the file extension for each -# generated HTML page (for example: .htm, .php, .asp). -# The default value is: .html. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_FILE_EXTENSION = .html - -# The HTML_HEADER tag can be used to specify a user-defined HTML header file for -# each generated HTML page. If the tag is left blank doxygen will generate a -# standard header. -# -# To get valid HTML the header file that includes any scripts and style sheets -# that doxygen needs, which is dependent on the configuration options used (e.g. -# the setting GENERATE_TREEVIEW). It is highly recommended to start with a -# default header using -# doxygen -w html new_header.html new_footer.html new_stylesheet.css -# YourConfigFile -# and then modify the file new_header.html. See also section "Doxygen usage" -# for information on how to generate the default header that doxygen normally -# uses. -# Note: The header is subject to change so you typically have to regenerate the -# default header when upgrading to a newer version of doxygen. For a description -# of the possible markers and block names see the documentation. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_HEADER = - -# The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each -# generated HTML page. If the tag is left blank doxygen will generate a standard -# footer. See HTML_HEADER for more information on how to generate a default -# footer and what special commands can be used inside the footer. See also -# section "Doxygen usage" for information on how to generate the default footer -# that doxygen normally uses. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_FOOTER = - -# The HTML_STYLESHEET tag can be used to specify a user-defined cascading style -# sheet that is used by each HTML page. It can be used to fine-tune the look of -# the HTML output. If left blank doxygen will generate a default style sheet. -# See also section "Doxygen usage" for information on how to generate the style -# sheet that doxygen normally uses. -# Note: It is recommended to use HTML_EXTRA_STYLESHEET instead of this tag, as -# it is more robust and this tag (HTML_STYLESHEET) will in the future become -# obsolete. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_STYLESHEET = - -# The HTML_EXTRA_STYLESHEET tag can be used to specify additional user-defined -# cascading style sheets that are included after the standard style sheets -# created by doxygen. Using this option one can overrule certain style aspects. -# This is preferred over using HTML_STYLESHEET since it does not replace the -# standard style sheet and is therefore more robust against future updates. -# Doxygen will copy the style sheet files to the output directory. -# Note: The order of the extra style sheet files is of importance (e.g. the last -# style sheet in the list overrules the setting of the previous ones in the -# list). For an example see the documentation. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_EXTRA_STYLESHEET = - -# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or -# other source files which should be copied to the HTML output directory. Note -# that these files will be copied to the base HTML output directory. Use the -# $relpath^ marker in the HTML_HEADER and/or HTML_FOOTER files to load these -# files. In the HTML_STYLESHEET file, use the file name only. Also note that the -# files will be copied as-is; there are no commands or markers available. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_EXTRA_FILES = - -# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen -# will adjust the colors in the style sheet and background images according to -# this color. Hue is specified as an angle on a colorwheel, see -# http://en.wikipedia.org/wiki/Hue for more information. For instance the value -# 0 represents red, 60 is yellow, 120 is green, 180 is cyan, 240 is blue, 300 -# purple, and 360 is red again. -# Minimum value: 0, maximum value: 359, default value: 220. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_COLORSTYLE_HUE = 220 - -# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of the colors -# in the HTML output. For a value of 0 the output will use grayscales only. A -# value of 255 will produce the most vivid colors. -# Minimum value: 0, maximum value: 255, default value: 100. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_COLORSTYLE_SAT = 100 - -# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to the -# luminance component of the colors in the HTML output. Values below 100 -# gradually make the output lighter, whereas values above 100 make the output -# darker. The value divided by 100 is the actual gamma applied, so 80 represents -# a gamma of 0.8, The value 220 represents a gamma of 2.2, and 100 does not -# change the gamma. -# Minimum value: 40, maximum value: 240, default value: 80. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_COLORSTYLE_GAMMA = 80 - -# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML -# page will contain the date and time when the page was generated. Setting this -# to YES can help to show when doxygen was last run and thus if the -# documentation is up to date. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_TIMESTAMP = NO - -# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML -# documentation will contain sections that can be hidden and shown after the -# page has loaded. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_DYNAMIC_SECTIONS = NO - -# With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries -# shown in the various tree structured indices initially; the user can expand -# and collapse entries dynamically later on. Doxygen will expand the tree to -# such a level that at most the specified number of entries are visible (unless -# a fully collapsed tree already exceeds this amount). So setting the number of -# entries 1 will produce a full collapsed tree by default. 0 is a special value -# representing an infinite number of entries and will result in a full expanded -# tree by default. -# Minimum value: 0, maximum value: 9999, default value: 100. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_INDEX_NUM_ENTRIES = 100 - -# If the GENERATE_DOCSET tag is set to YES, additional index files will be -# generated that can be used as input for Apple's Xcode 3 integrated development -# environment (see: http://developer.apple.com/tools/xcode/), introduced with -# OSX 10.5 (Leopard). To create a documentation set, doxygen will generate a -# Makefile in the HTML output directory. Running make will produce the docset in -# that directory and running make install will install the docset in -# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find it at -# startup. See http://developer.apple.com/tools/creatingdocsetswithdoxygen.html -# for more information. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -GENERATE_DOCSET = NO - -# This tag determines the name of the docset feed. A documentation feed provides -# an umbrella under which multiple documentation sets from a single provider -# (such as a company or product suite) can be grouped. -# The default value is: Doxygen generated docs. -# This tag requires that the tag GENERATE_DOCSET is set to YES. - -DOCSET_FEEDNAME = "Doxygen generated docs" - -# This tag specifies a string that should uniquely identify the documentation -# set bundle. This should be a reverse domain-name style string, e.g. -# com.mycompany.MyDocSet. Doxygen will append .docset to the name. -# The default value is: org.doxygen.Project. -# This tag requires that the tag GENERATE_DOCSET is set to YES. - -DOCSET_BUNDLE_ID = org.doxygen.Project - -# The DOCSET_PUBLISHER_ID tag specifies a string that should uniquely identify -# the documentation publisher. This should be a reverse domain-name style -# string, e.g. com.mycompany.MyDocSet.documentation. -# The default value is: org.doxygen.Publisher. -# This tag requires that the tag GENERATE_DOCSET is set to YES. - -DOCSET_PUBLISHER_ID = org.doxygen.Publisher - -# The DOCSET_PUBLISHER_NAME tag identifies the documentation publisher. -# The default value is: Publisher. -# This tag requires that the tag GENERATE_DOCSET is set to YES. - -DOCSET_PUBLISHER_NAME = Publisher - -# If the GENERATE_HTMLHELP tag is set to YES then doxygen generates three -# additional HTML index files: index.hhp, index.hhc, and index.hhk. The -# index.hhp is a project file that can be read by Microsoft's HTML Help Workshop -# (see: http://www.microsoft.com/en-us/download/details.aspx?id=21138) on -# Windows. -# -# The HTML Help Workshop contains a compiler that can convert all HTML output -# generated by doxygen into a single compiled HTML file (.chm). Compiled HTML -# files are now used as the Windows 98 help format, and will replace the old -# Windows help format (.hlp) on all Windows platforms in the future. Compressed -# HTML files also contain an index, a table of contents, and you can search for -# words in the documentation. The HTML workshop also contains a viewer for -# compressed HTML files. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -GENERATE_HTMLHELP = NO - -# The CHM_FILE tag can be used to specify the file name of the resulting .chm -# file. You can add a path in front of the file if the result should not be -# written to the html output directory. -# This tag requires that the tag GENERATE_HTMLHELP is set to YES. - -CHM_FILE = - -# The HHC_LOCATION tag can be used to specify the location (absolute path -# including file name) of the HTML help compiler (hhc.exe). If non-empty, -# doxygen will try to run the HTML help compiler on the generated index.hhp. -# The file has to be specified with full path. -# This tag requires that the tag GENERATE_HTMLHELP is set to YES. - -HHC_LOCATION = - -# The GENERATE_CHI flag controls if a separate .chi index file is generated -# (YES) or that it should be included in the master .chm file (NO). -# The default value is: NO. -# This tag requires that the tag GENERATE_HTMLHELP is set to YES. - -GENERATE_CHI = NO - -# The CHM_INDEX_ENCODING is used to encode HtmlHelp index (hhk), content (hhc) -# and project file content. -# This tag requires that the tag GENERATE_HTMLHELP is set to YES. - -CHM_INDEX_ENCODING = - -# The BINARY_TOC flag controls whether a binary table of contents is generated -# (YES) or a normal table of contents (NO) in the .chm file. Furthermore it -# enables the Previous and Next buttons. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTMLHELP is set to YES. - -BINARY_TOC = NO - -# The TOC_EXPAND flag can be set to YES to add extra items for group members to -# the table of contents of the HTML help documentation and to the tree view. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTMLHELP is set to YES. - -TOC_EXPAND = NO - -# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and -# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated that -# can be used as input for Qt's qhelpgenerator to generate a Qt Compressed Help -# (.qch) of the generated HTML documentation. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -GENERATE_QHP = NO - -# If the QHG_LOCATION tag is specified, the QCH_FILE tag can be used to specify -# the file name of the resulting .qch file. The path specified is relative to -# the HTML output folder. -# This tag requires that the tag GENERATE_QHP is set to YES. - -QCH_FILE = - -# The QHP_NAMESPACE tag specifies the namespace to use when generating Qt Help -# Project output. For more information please see Qt Help Project / Namespace -# (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#namespace). -# The default value is: org.doxygen.Project. -# This tag requires that the tag GENERATE_QHP is set to YES. - -QHP_NAMESPACE = org.doxygen.Project - -# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating Qt -# Help Project output. For more information please see Qt Help Project / Virtual -# Folders (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#virtual- -# folders). -# The default value is: doc. -# This tag requires that the tag GENERATE_QHP is set to YES. - -QHP_VIRTUAL_FOLDER = doc - -# If the QHP_CUST_FILTER_NAME tag is set, it specifies the name of a custom -# filter to add. For more information please see Qt Help Project / Custom -# Filters (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom- -# filters). -# This tag requires that the tag GENERATE_QHP is set to YES. - -QHP_CUST_FILTER_NAME = - -# The QHP_CUST_FILTER_ATTRS tag specifies the list of the attributes of the -# custom filter to add. For more information please see Qt Help Project / Custom -# Filters (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom- -# filters). -# This tag requires that the tag GENERATE_QHP is set to YES. - -QHP_CUST_FILTER_ATTRS = - -# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this -# project's filter section matches. Qt Help Project / Filter Attributes (see: -# http://qt-project.org/doc/qt-4.8/qthelpproject.html#filter-attributes). -# This tag requires that the tag GENERATE_QHP is set to YES. - -QHP_SECT_FILTER_ATTRS = - -# The QHG_LOCATION tag can be used to specify the location of Qt's -# qhelpgenerator. If non-empty doxygen will try to run qhelpgenerator on the -# generated .qhp file. -# This tag requires that the tag GENERATE_QHP is set to YES. - -QHG_LOCATION = - -# If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files will be -# generated, together with the HTML files, they form an Eclipse help plugin. To -# install this plugin and make it available under the help contents menu in -# Eclipse, the contents of the directory containing the HTML and XML files needs -# to be copied into the plugins directory of eclipse. The name of the directory -# within the plugins directory should be the same as the ECLIPSE_DOC_ID value. -# After copying Eclipse needs to be restarted before the help appears. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -GENERATE_ECLIPSEHELP = NO - -# A unique identifier for the Eclipse help plugin. When installing the plugin -# the directory name containing the HTML and XML files should also have this -# name. Each documentation set should have its own identifier. -# The default value is: org.doxygen.Project. -# This tag requires that the tag GENERATE_ECLIPSEHELP is set to YES. - -ECLIPSE_DOC_ID = org.doxygen.Project - -# If you want full control over the layout of the generated HTML pages it might -# be necessary to disable the index and replace it with your own. The -# DISABLE_INDEX tag can be used to turn on/off the condensed index (tabs) at top -# of each HTML page. A value of NO enables the index and the value YES disables -# it. Since the tabs in the index contain the same information as the navigation -# tree, you can set this option to YES if you also set GENERATE_TREEVIEW to YES. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -DISABLE_INDEX = NO - -# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index -# structure should be generated to display hierarchical information. If the tag -# value is set to YES, a side panel will be generated containing a tree-like -# index structure (just like the one that is generated for HTML Help). For this -# to work a browser that supports JavaScript, DHTML, CSS and frames is required -# (i.e. any modern browser). Windows users are probably better off using the -# HTML help feature. Via custom style sheets (see HTML_EXTRA_STYLESHEET) one can -# further fine-tune the look of the index. As an example, the default style -# sheet generated by doxygen has an example that shows how to put an image at -# the root of the tree instead of the PROJECT_NAME. Since the tree basically has -# the same information as the tab index, you could consider setting -# DISABLE_INDEX to YES when enabling this option. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -GENERATE_TREEVIEW = YES - -# The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that -# doxygen will group on one line in the generated HTML documentation. -# -# Note that a value of 0 will completely suppress the enum values from appearing -# in the overview section. -# Minimum value: 0, maximum value: 20, default value: 4. -# This tag requires that the tag GENERATE_HTML is set to YES. - -ENUM_VALUES_PER_LINE = 1 - -# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be used -# to set the initial width (in pixels) of the frame in which the tree is shown. -# Minimum value: 0, maximum value: 1500, default value: 250. -# This tag requires that the tag GENERATE_HTML is set to YES. - -TREEVIEW_WIDTH = 250 - -# If the EXT_LINKS_IN_WINDOW option is set to YES, doxygen will open links to -# external symbols imported via tag files in a separate window. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -EXT_LINKS_IN_WINDOW = NO - -# Use this tag to change the font size of LaTeX formulas included as images in -# the HTML documentation. When you change the font size after a successful -# doxygen run you need to manually remove any form_*.png images from the HTML -# output directory to force them to be regenerated. -# Minimum value: 8, maximum value: 50, default value: 10. -# This tag requires that the tag GENERATE_HTML is set to YES. - -FORMULA_FONTSIZE = 10 - -# Use the FORMULA_TRANPARENT tag to determine whether or not the images -# generated for formulas are transparent PNGs. Transparent PNGs are not -# supported properly for IE 6.0, but are supported on all modern browsers. -# -# Note that when changing this option you need to delete any form_*.png files in -# the HTML output directory before the changes have effect. -# The default value is: YES. -# This tag requires that the tag GENERATE_HTML is set to YES. - -FORMULA_TRANSPARENT = YES - -# Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see -# http://www.mathjax.org) which uses client side Javascript for the rendering -# instead of using pre-rendered bitmaps. Use this if you do not have LaTeX -# installed or if you want to formulas look prettier in the HTML output. When -# enabled you may also need to install MathJax separately and configure the path -# to it using the MATHJAX_RELPATH option. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -USE_MATHJAX = NO - -# When MathJax is enabled you can set the default output format to be used for -# the MathJax output. See the MathJax site (see: -# http://docs.mathjax.org/en/latest/output.html) for more details. -# Possible values are: HTML-CSS (which is slower, but has the best -# compatibility), NativeMML (i.e. MathML) and SVG. -# The default value is: HTML-CSS. -# This tag requires that the tag USE_MATHJAX is set to YES. - -MATHJAX_FORMAT = HTML-CSS - -# When MathJax is enabled you need to specify the location relative to the HTML -# output directory using the MATHJAX_RELPATH option. The destination directory -# should contain the MathJax.js script. For instance, if the mathjax directory -# is located at the same level as the HTML output directory, then -# MATHJAX_RELPATH should be ../mathjax. The default value points to the MathJax -# Content Delivery Network so you can quickly see the result without installing -# MathJax. However, it is strongly recommended to install a local copy of -# MathJax from http://www.mathjax.org before deployment. -# The default value is: http://cdn.mathjax.org/mathjax/latest. -# This tag requires that the tag USE_MATHJAX is set to YES. - -MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest - -# The MATHJAX_EXTENSIONS tag can be used to specify one or more MathJax -# extension names that should be enabled during MathJax rendering. For example -# MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols -# This tag requires that the tag USE_MATHJAX is set to YES. - -MATHJAX_EXTENSIONS = - -# The MATHJAX_CODEFILE tag can be used to specify a file with javascript pieces -# of code that will be used on startup of the MathJax code. See the MathJax site -# (see: http://docs.mathjax.org/en/latest/output.html) for more details. For an -# example see the documentation. -# This tag requires that the tag USE_MATHJAX is set to YES. - -MATHJAX_CODEFILE = - -# When the SEARCHENGINE tag is enabled doxygen will generate a search box for -# the HTML output. The underlying search engine uses javascript and DHTML and -# should work on any modern browser. Note that when using HTML help -# (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets (GENERATE_DOCSET) -# there is already a search function so this one should typically be disabled. -# For large projects the javascript based search engine can be slow, then -# enabling SERVER_BASED_SEARCH may provide a better solution. It is possible to -# search using the keyboard; to jump to the search box use + S -# (what the is depends on the OS and browser, but it is typically -# , /