add README updated for file system override

Author: JacobBarthelmeh

ide/mplabx/README.md

@@ -1,54 +1,145 @@
 # wolfSSH MPLABX
 
-This is example project to create a wolfSSH library and example code for adding
-a wolfSSH echoserver to a MPLABX project.
+This is an example project demonstrating how to build the `wolfSSH` library and
+ use it to add a SSH server to an MPLABX project.
 
-Tested on a ATSAMV71Q21B with MPLABX version 6.20.
+Tested on an **ATSAMV71Q21B** using **MPLABX version 6.20**.
 
-### Building wolfSSH library
+---
 
-The library project is located at ide/mplabx/wolfssh.X
+## Building the wolfSSH Library
 
-- First open wolfssh.X with MPLABX IDE then click on "CM" content manager and
-import the ide/mplabx/wolfssh.X/mcc-manifest-generated-success.yml file.
-- Click apply.
-- Next click "MCC" and "generate".
-- To build from the command line, do the following after the XC32 toolchain has
-been installed.
+The library project is located at:
 
 ```
+
+ide/mplabx/wolfssh.X
+
+```
+
+### Using MPLABX IDE
+
+1. Open the `wolfssh.X` project in MPLABX.
+2. Click **CM (Content Manager)** and import the manifest:
+
+```
+
+ide/mplabx/wolfssh.X/mcc-manifest-generated-success.yml
+
+````
+
+3. Click **Apply**.
+4. Click **MCC** and then **Generate**.
+5. Build the project via the IDE (hammer icon or `Run → Build Project`).
+
+### Using the Command Line
+
+After installing the XC32 toolchain:
+
+```sh
 cd ide/mplabx/wolfssh.X
 make
+````
+
+This produces:
+
+```
+ide/mplabx/wolfssh.X/dist/default/production/wolfssh.X.a
 ```
 
-- To build using the IDE open the project ide/mplabx/wolfssh.X and click build.
+> **Important:** The application and wolfSSL must be built using the **same**
+ `user_settings.h` as used for the wolfSSH library. Mismatched macros can result
+ in undefined behavior or crashes.
 
+---
 
-This will produce a wolfssh.X.a library in the directory
-ide/mplabx/wolfssh.X/dist/default/production/wolfssh.X.a
+## Building the Example Application
+
+### Steps:
+
+1. **Set Preprocessor Macros**:
+
+   * Define `WOLFSSL_USER_SETTINGS`.
+   * Add include path to `ide/mplabx/user_settings.h`.
+
+2. **Remove** the generated `app.c` from Source Files.
+
+3. **Link the wolfSSH Library**:
+
+   * Go to **Project Properties → Libraries → Add Library/Object File**.
+   * Select `wolfssh.X.a`.
 
-The application and wolfSSL must be built with the same user_settings.h as the
-wolfSSH library was built with! Differences in macro's defined for
-configuration will cause undefined behavior and potential crashes.
+4. **Add Source File**:
 
-### Building an example app
+   * Right-click the project → **Add Existing Item**.
+   * Select `ide/mplabx/wolfssh.c`.
 
-1) Adjust the "Preprocessor macros" to include WOLFSSL_USER_SETTINGS and add an
- include path to ide/mplabx/user_settings.h.
-2) Remove the generated app.c from Source File
-3) Link to the wolfssh.X.a library. Properties->Libraries->Add Library/Object
- File...
-4) Right click on the project and add existing item. Select ide/mplabx/wolfssh.c
-5) Increase the heap size to 200,000 by right clicking on the project, selecting
- "Properties"->"x32-ld"
+5. **Increase Heap Size**:
+
+   * Right-click the project → **Properties → XC32-ld**.
+   * Set heap size to at least **200,000**.
+
+### Notes
+
+* Tested with heap and stack sizes of **200,000**.
+* TX buffer size: **1024 bytes**.
+* Tested with `wolfSSH version 1.4.20`.
+
+After flashing the board, a wolfSSH server will be listening on port **22**.
+You can connect using the provided client:
+
+```sh
+./examples/client/client -u jill -P upthehill -h 192.168.1.120 -p 22
+```
+
+---
+
+## Overriding the File System for SFTP
+
+This example shows how to override the SFTP file system interface and apply
+ restrictions based on the logged-in user. It uses Microchip's file system but
+ the approach is generic.
+
+### Enabling a Custom File System
+
+1. **Define `WOLFSSH_USER_FILESYSTEM`** in `user_settings.h`.
+
+2. **Provide `myFilesystem.h`**:
+
+   * Required when `WOLFSSH_USER_FILESYSTEM` is defined.
+   * Ensure it's in your include path (e.g., move it to the wolfSSH `include/` directory).
+
+3. **Add `myFilesystem.c`** to the wolfSSH project.
+
+4. **Recompile** the library.
+
+### Example File Operation Categories
+
+* **Safe operations**: Navigation, file downloads.
+* **Restricted operations**: Modifying or deleting files.
+
+Set the custom file system handle as follows:
+
+```c
+wolfSSH_SetFilesystemHandle(ssh, (void*)ssh);
+```
+
+### Integration Example (in `wolfssh.c`)
+
+```c
+case APP_SSH_SFTP_START:
+    SYS_CONSOLE_PRINT("Setting starting SFTP directory to [%s]\r\n", "/mnt/myDrive1");
+    if (wolfSSH_SFTP_SetDefaultPath(ssh, "/mnt/myDrive1") != WS_SUCCESS) {
+        SYS_CONSOLE_PRINT("Error setting starting directory\r\n");
+        SYS_CONSOLE_PRINT("Error = %d\r\n", wolfSSH_get_error(ssh));
+        appData.state = APP_SSH_CLEANUP;
+    }
+    wolfSSH_SetFilesystemHandle(ssh, (void*)ssh);
+    appData.state = APP_SSH_SFTP;
+    break;
+```
 
-Notes:
+### Privileged Access
 
-For the current project this was tested with the heap and stack set to 200,000
- each. This was not trimed to see the minumum possible heap and stack usage yet.
- The TX buffer size used was set to 1024. The example was developed with wolfssh
- version 1.4.20.
+Logging in as user `admin` with password `fetchapail` enables restricted operations.
 
-After building and flashing the board a wolfSSH echoserver will be open on port
- 22 which can be connected to by using the example client bundled with wolfSSH.
- ```./examples/client/client -u jill -P upthehill -h 192.168.1.120 -p 22```