docs: lots of examples and docs

README.md

@@ -8,124 +8,19 @@
 
 ## Packages
 
-- `atchops` stands for cryptographic and hashing operations catered for the atProtocol, uses [MbedTLS crypto](https://github.com/Mbed-TLS/mbedtls) as a dependency.
-- `atclient` is the core dependency for anything Atsign technology related. atclient depends on [atchops](./packages/atchops/README.md) and [MbedTLS](https://github.com/Mbed-TLS/mbedtls)
-- `repl` is a demo application using atclient
+- [atchops](./packages/atchops/README.md) stands for cryptographic and hashing operations catered for the atProtocol, uses [MbedTLS crypto](https://github.com/Mbed-TLS/mbedtls) as a dependency.
+- [atclient](./packages/atclient/README.md) is the core dependency for anything Atsign technology related. atclient depends on [atchops](./packages/atchops/README.md) and [MbedTLS](https://github.com/Mbed-TLS/mbedtls)
+- [atclient_espidf](./packages/atclient_espidf/README.md)
 
-## Building Source
+## Examples
 
-To build the source code you will need to have [CMake](https://cmake.org/) installed.
-
-Most of the following steps will work with `atchops` and `atclient`:
-
-- [Installing on Linux/MacOS](#installing-on-linuxmacos)
-- [Running Tests on Linux/MacOS](#running-tests-on-linuxmacos)
-- [Installing on Windows](#installing-on-windows)
-
-### Installing on Linux/MacOS
-
-1. Get ahold of the source code either via git clone or from downloading the source from our releases:
-
-```sh
-git clone https://github.com/atsign-foundation/at_c.git
-cd at_c/packages/atclient
-```
-
-2. CMake configure
-
-```sh
-cmake -S . -B build
-```
-
-Alternatively, if you have installed MbedTLS and/or AtChops from source already, you can avoid fetching it everytime with `ATCLIENT_FETCH_MBEDTLS=OFF` and `ATCLIENT_FETCH_ATCHOPS=OFF` respectively. Doing this drastically reduces the time it takes to configure the project:
-
-```sh
-cmake -S . -B build -DATCLIENT_FETCH_MBEDTLS=OFF -DATCLIENT_FETCH_ATCHOPS=OFF
-```
-
-3. Install
-
-```sh
-cmake --build build --target install
-```
-
-4. Building the source code will allow you to use the `atclient` library in your own CMake projects:
-
-```cmake
-find_package(atclient REQUIRED CONFIG)
-target_link_libraries(myproj PRIVATE atclient::atclient)
-```
-
-### Running Tests on Linux/MacOS
-
-1. Get ahold of the source code either via git clone or from downloading the source from our releases:
-
-```sh
-git clone https://github.com/atsign-foundation/at_c.git
-cd at_c/packages/atclient
-```
-
-2. CMake configure with `-DATCLIENT_BUILD_TESTS=ON`
-
-```sh
-cmake -S . -B build -DATCLIENT_BUILD_TESTS=ON
-```
-
-3. Build (target is all by default)
-
-```sh
-cmake --build build
-```
-
-4. Run tests
-
-```sh
-cd build/tests && ctest -V --output-on-failure --timeout 10
-```
-
-`--timeout 10` times out tests after 10 seconds
-
-### Installing on Windows
-
-Coming Soon!
+- [repl](./examples/repl/README.md) is a command line interface for interacting with the atProtocol. Works on Desktop Linux/MacOS.
 
 ## Contributing
 
 Read [CONTRIBUTING.md](./CONTRIBUTING.md) for information on how to properly fork and open a pull request.
 
-When creating 
-
-- [Creating Tests](#creating-tests)
-- [Adding New Source Files](#adding-new-source-files)
-- [Adding New Include Headers](#adding-new-include-headers)
-
-### Creating Tests
-
-If you want to add a test in atclient, simply add a `test_*.c` file in the `tests` directory. CMake will automatically detect it and add it to the test suite. Ensure that the test file is named `test_*.c` or else it will not be detected.
-
-Ensure the file has a `int main(int argc, char **argv)` function and returns 0 on success and not 0 on failure.
-
-### Adding New Source Files
-
-This one is a little more tricky. Adding a new source file to the project requires a few steps:
-
-Add the source file to the `CMakeLists.txt` file in the `src` directory. This is so that CMake knows to compile the file.
-
-Example:
-
-```cmake
-target_sources(atclient PRIVATE
-    ...
-    ${CMAKE_CURRENT_LIST_DIR}/src/folder/new_file.c
-    ...
-)
-```
-
-### Adding New Include Headers
-
-Simply add the header inside of the `include/` directory. CMake will automatically detect it and add it to the include path.
-
-If it is added in a subdirectory (like `include/atclient/`), then the include path will be `atclient/` (e.g. `#include <atclient/new_header.h>`)
+When creating source files, include headers, or tests to certain packages, please follow the documentation in their according README files.
 
 ## Maintainers
 

examples/atclient_esp32_source/CMakeLists.txt

@@ -0,0 +1,10 @@
+cmake_minimum_required(VERSION 3.19)
+
+set(EXTRA_COMPONENT_DIRS
+    ${CMAKE_SOURCE_DIR}/../../packages/atclient # match this to be the path to the root CMakeLists.txt of atclient package
+    ${CMAKE_SOURCE_DIR}/../../packages/atchops # match this to be the path to the root CMakeLists.txt of atchops package
+)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+
+project(atclient_esp32_source)

examples/atclient_esp32_source/README.md

@@ -0,0 +1,37 @@
+# atclient_esp32_source
+
+This example shows you how to use atclient/atchops in your own ESP-IDF project by providing the path to the source code.
+
+## How to Consume Via Source Code
+
+In `make/CMakeLists.txt`, be sure to add the atclient and atchops components to the REQUIRES list:
+
+```cmake
+idf_component_register(
+    SRCS "main.c"
+    REQUIRES mbedtls atclient atchops
+)
+```
+
+In `./CMakeLists.txt`, add the path to the atclient and atchops source code via the EXTRA_COMPONENT_DIRS variable:
+
+```cmake
+set(EXTRA_COMPONENT_DIRS
+    ${CMAKE_SOURCE_DIR}/../../packages/atclient # match this to be the path to the root CMakeLists.txt of atclient package
+    ${CMAKE_SOURCE_DIR}/../../packages/atchops # match this to be the path to the root CMakeLists.txt of atchops package
+)
+```
+
+## Running the Example
+
+To run the example, you will need the ESP-IDF toolchain installed. See [ESP-IDF's Getting Started Guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html) for more information. Ensure that your ESP32 is plugged into your computer with a micro USB data cable.
+
+Running the example via `get_idf && idf.py build && idf.py flash monitor` will give you something similar to:
+
+```sh
+atchops_base64_encode: 0
+src: Lemonade!
+dst: TGVtb25hZGUh
+dst bytes: 
+54 47 56 74 62 32 35 68 5a 47 55 68
+```

examples/atclient_esp32_source/main/CMakeLists.txt

@@ -0,0 +1,4 @@
+idf_component_register(
+    SRCS "main.c"
+    REQUIRES mbedtls atclient atchops
+)

examples/atclient_esp32_source/main/main.c

@@ -0,0 +1,28 @@
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include "atchops/base64.h"
+
+void app_main(void)
+{
+    const char *src = "Lemonade!";
+    unsigned long srclen = strlen(src);
+
+    const unsigned long dstlen = 2048;
+    const unsigned char *dst = malloc(sizeof(unsigned char) * dstlen);
+    memset(dst, 0, dstlen);
+    unsigned long dstolen = 0; // written length
+
+    int ret = atchops_base64_encode((const unsigned char *) src, srclen, dst, dstlen, &dstolen);
+
+    printf("atchops_base64_encode: %d\n", ret);
+
+    printf("src: %s\n", src);
+    printf("dst: %.*s\n", (int) dstolen, dst);
+    printf("dst bytes: \n");
+    for(int i = 0; i < dstolen; i++)
+    {
+        printf("%02x ", *(dst + i));
+    }
+    printf("\n");
+}

examples/atclient_esp32_static_components/CMakeLists.txt

@@ -0,0 +1,5 @@
+cmake_minimum_required(VERSION 3.19)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+
+project(atclient_esp32_static_components)