From 4acad717fe14e2846fb1847916f78d05be88230a Mon Sep 17 00:00:00 2001 From: raiden00pl Date: Tue, 24 Oct 2023 14:04:46 +0200 Subject: [PATCH] remove system/xxx/README.md. Migrated to Documentation/applications/system --- system/cdcacm/README.md | 36 --- system/cfgdata/README.md | 22 -- system/composite/README.md | 69 ------ system/flash_eraseall/README.md | 15 -- system/i2c/README.md | 387 -------------------------------- system/libuv/README.md | 17 -- system/nsh/README.md | 50 ----- system/nxplayer/README.md | 18 -- system/psmq/README.md | 61 ----- system/spi/README.md | 246 -------------------- system/termcurses/README.md | 50 ----- system/trace/README.md | 4 - system/usbmsc/README.md | 85 ------- system/ymodem/README.md | 51 ----- system/zmodem/README.md | 280 ----------------------- 15 files changed, 1391 deletions(-) delete mode 100644 system/cdcacm/README.md delete mode 100644 system/cfgdata/README.md delete mode 100644 system/composite/README.md delete mode 100644 system/flash_eraseall/README.md delete mode 100644 system/i2c/README.md delete mode 100644 system/libuv/README.md delete mode 100644 system/nsh/README.md delete mode 100644 system/nxplayer/README.md delete mode 100644 system/psmq/README.md delete mode 100644 system/spi/README.md delete mode 100644 system/termcurses/README.md delete mode 100644 system/trace/README.md delete mode 100644 system/usbmsc/README.md delete mode 100644 system/ymodem/README.md delete mode 100644 system/zmodem/README.md diff --git a/system/cdcacm/README.md b/system/cdcacm/README.md deleted file mode 100644 index 61fc9cab6..000000000 --- a/system/cdcacm/README.md +++ /dev/null @@ -1,36 +0,0 @@ -# System / `cdcacm` USB CDC/ACM serial - -This very simple add-on allows the USB CDC/ACM serial device can be dynamically -connected and disconnected from a host. This add-on can only be used as an NSH -built-in command. If built-in, then two new NSH commands will be supported: - -1. `sercon` – Connect the CDC/ACM serial device -2. `serdis` – Disconnect the CDC/ACM serial device - -Configuration prerequisites (not complete): - -- `CONFIG_USBDEV=y` – USB device support must be enabled -- `CONFIG_CDCACM=y` – The CDC/ACM driver must be built - -Configuration options specific to this add-on: - -- `CONFIG_SYSTEM_CDCACM_DEVMINOR` – The minor number of the CDC/ACM device, - i.e., the `x` in `/dev/ttyACMx`. - -If `CONFIG_USBDEV_TRACE` is enabled (or `CONFIG_DEBUG_FEATURES` and -`CONFIG_DEBUG_USB`, or `CONFIG_USBDEV_TRACE`), then the add-on code will also -initialize the USB trace output. The amount of trace output can be controlled -using: - -- `CONFIG_SYSTEM_CDCACM_TRACEINIT` – Show initialization events. -- `CONFIG_SYSTEM_CDCACM_TRACECLASS` – Show class driver events. -- `CONFIG_SYSTEM_CDCACM_TRACETRANSFERS` – Show data transfer events. -- `CONFIG_SYSTEM_CDCACM_TRACECONTROLLER` – Show controller events. -- `CONFIG_SYSTEM_CDCACM_TRACEINTERRUPTS` – Show interrupt-related events. - -**Note**: This add-on is only enables or disable USB CDC/ACM via the NSH -`sercon` and `serdis` command. It will enable and disable tracing per the -settings before enabling and after disabling the CDC/ACM device. It will not, -however, monitor buffered trace data in the interim. If `CONFIG_USBDEV_TRACE` is -defined (and the debug options are not), other application logic will need to -monitor the buffered trace data. diff --git a/system/cfgdata/README.md b/system/cfgdata/README.md deleted file mode 100644 index f3768019f..000000000 --- a/system/cfgdata/README.md +++ /dev/null @@ -1,22 +0,0 @@ -# System / `cfgdata` - -``` -Author: Ken Pettit - Date: 18 December 2018 -``` - -This application provides a command line interface for managing platform -specific configdata within the `/dev/config` device. - -**Usage**: - -```shell -config [arguments] -``` - -Where `` is one of: - -- `all` – show all config entries -- `print` – display a specific config entry -- `set` – set or change a config entry -- `unset` – delete a config entry diff --git a/system/composite/README.md b/system/composite/README.md deleted file mode 100644 index 6e4d89bb8..000000000 --- a/system/composite/README.md +++ /dev/null @@ -1,69 +0,0 @@ -# System / `composite` USB Composite - -This logic adds a NSH command to control a USB composite device. The only -supported devices in the composite are CDC/ACM serial and a USB mass storage -device. Which devices are enclosed in a composite device is configured with an -array of configuration-structs, handed over to the function -`composite_initialize()`. - -Required overall configuration: - -Enable the USB Support of your Hardware / Processor e.g. `SAMV7_USBDEVHS=y` - -- `CONFIG_USBDEV=y` – USB device support. -- `CONFIG_USBDEV_COMPOSITE=y` – USB composite device support. -- `CONFIG_COMPOSITE_IAD=y` – Interface associate descriptor needed. -- `CONFIG_CDCACM=y` – USB CDC/ACM serial device support. -- `CONFIG_CDCACM_COMPOSITE=y` – USB CDC/ACM serial composite device support. - -The interface-, string-descriptor- and endpoint-numbers are configured via the -configuration-structs as noted above. The CDC/ACM serial device needs three -endpoints; one interrupt-driven and two bulk endpoints. - -- `CONFIG_USBMSC=y` – USB mass storage device support. -- `CONFIG_USBMSC_COMPOSITE=y` – USB mass storage composite device support. - -Like the configuration for the CDC/ACM, the descriptor- and endpoint-numbers are -configured via the configuration struct. - -Depending on the configuration struct you need to configure different vendor- -and product-IDs. Each `VID`/`PID` is unique to a device and thus to a dedicated -configuration. - -Linux tries to detect the device types and installs default drivers if the -`VID`/`PID` pair is unknown. - -Windows insists on a known and installed configuration. With an Atmel hardware -and Atmel-Studio or the Atmel-USB-drivers installed, you can test your -configuration with Atmel Example Vendor- and Product-IDs. - -If you have a USBMSC and a CDC/ACM configured in your combo, then you can try to -use - -- `VID = 0x03EB` (ATMEL) -- `PID = 0x2424` (ASF Example with MSC and CDC) - -If for example you try to test a configuration with up to seven CDCs, then - -- `VID = 0x03EB` (ATMEL) -- `PID = 0x2426` (ASF Example with up to seven CDCs) - -This add-on can be built as two NSH _built-in_ commands: - -- `CONFIG_NSH_BUILTIN_APPS` – if this option is selected: `conn` will connect - the USB composite device; `disconn` will disconnect the USB composite device. - -Configuration options unique to this add-on: - -- `CONFIG_SYSTEM_COMPOSITE_DEBUGMM` – Enables some debug tests to check for - memory usage and memory leaks. - -If `CONFIG_USBDEV_TRACE` is enabled (or `CONFIG_DEBUG_FEATURES` and -`CONFIG_DEBUG_USB`), then the add-on code will also manage the USB trace output. -The amount of trace output can be controlled using: - -- `CONFIG_SYSTEM_COMPOSITE_TRACEINIT` – Show initialization events. -- `CONFIG_SYSTEM_COMPOSITE_TRACECLASS` – Show class driver events. -- `CONFIG_SYSTEM_COMPOSITE_TRACETRANSFERS` – Show data transfer events. -- `CONFIG_SYSTEM_COMPOSITE_TRACECONTROLLER` – Show controller events. -- `CONFIG_SYSTEM_COMPOSITE_TRACEINTERRUPTS` – Show interrupt-related events. diff --git a/system/flash_eraseall/README.md b/system/flash_eraseall/README.md deleted file mode 100644 index 64d485def..000000000 --- a/system/flash_eraseall/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# System / `flash_eraseall` Flash Erase-All - -``` -Author: Ken Pettit - Date: 5 May 2013 -``` - -This application erases the FLASH of an MTD flash block. It is simply a wrapper -that calls the NuttX `flash_eraseall` interface. - -**Usage**: - -```shell -flash_eraseall -``` diff --git a/system/i2c/README.md b/system/i2c/README.md deleted file mode 100644 index 0d005664c..000000000 --- a/system/i2c/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# System / `i2c` I2C Tool - -The I2C tool provides a way to debug I2C related problems. This README file will -provide usage information for the I2C tools. - -## Contents - -- System Requirements - - I2C Driver - - Configuration Options -- Help -- Common Line Form -- Common Command Options - - _Sticky_ Options - - Environment variables - - Common Option Summary -- Command summary - - `bus` - - `dev` - - `get` - - `set` - - `verf` -- I2C Build Configuration - - NuttX Configuration Requirements - - I2C Tool Configuration Options - -## System Requirements - -The I2C tool is designed to be implemented as a NuttShell (NSH) add-on. Read the -`apps/nshlib/README.md` file for information about add-ons. - -### Configuration Options - -- `CONFIG_NSH_BUILTIN_APPS` – Build the tools as an NSH built-in command. -- `CONFIG_I2CTOOL_MINBUS` – Smallest bus index supported by the hardware - (default `0`). -- `CONFIG_I2CTOOL_MAXBUS` – Largest bus index supported by the hardware - (default `3`). -- `CONFIG_I2CTOOL_MINADDR` – Minimum device address (default: `0x03`). -- `CONFIG_I2CTOOL_MAXADDR` – Largest device address (default: `0x77`). -- `CONFIG_I2CTOOL_MAXREGADDR` – Largest register address (default: `0xff`). -- `CONFIG_I2CTOOL_DEFFREQ` – Default frequency (default: `4000000`). - -## Help - -First of all, the I2C tools supports a pretty extensive help output. That help -output can be view by entering either: - -``` -nsh> i2c help -``` - -or - -``` -nsh> i2c ? -``` - -Here is an example of the help output. I shows the general form of the command -line, the various I2C commands supported with their unique command line options, -and a more detailed summary of the command I2C command options. - -``` -nsh> i2c help - -Usage: i2c [arguments] -Where is one of: - - Show help : ? - List buses : bus - List devices : dev [OPTIONS] - Read register : get [OPTIONS] [] - Show help : help - Write register: set [OPTIONS] [] - Verify access : verf [OPTIONS] [] - - Where common _sticky_ OPTIONS include: - [-a addr] is the I2C device address (hex). Default: 03 Current: 03 - [-b bus] is the I2C bus number (decimal). Default: 1 Current: 1 - [-r regaddr] is the I2C device register address (hex). Default: 00 Current: 00 - [-w width] is the data width (8 or 16 decimal). Default: 8 Current: 8 - [-s|n], send/don't send start between command and data. Default: -n Current: -n - [-i|j], Auto increment|don't increment regaddr on repetitions. Default: NO Current: NO - [-f freq] I2C frequency. Default: 100000 Current: 100000 -``` - -**Notes**: - -- An environment variable like `$PATH` may be used for any argument. -- Arguments are _sticky_. For example, once the I2C address is specified, that - address will be re-used until it is changed. - -**Warning**: - -- The I2C dev command may have bad side effects on your I2C devices. Use only at - your own risk. - -## Command Line Form - -The I2C is started from NSH by invoking the `i2c` command from the NSH command -line. The general form of the `i2c` command is: - -```shell -i2c [arguments] -``` - -Where `` is a _sub-command_ and identifies one I2C operations supported by -the tool. `[arguments]` represents the list of arguments needed to perform the -I2C operation. Those arguments vary from command to command as described below. -However, there is also a core set of common `OPTIONS` supported by all commands. -So perhaps a better representation of the general I2C command would be: - -```shell -i2c [OPTIONS] [arguments] -``` - -Where `[OPTIONS]` represents the common options and and arguments represent the -operation-specific arguments. - -## Common Command Options - -### _Sticky_ Options - -In order to interact with I2C devices, there are a number of I2C parameters that -must be set correctly. One way to do this would be to provide to set the value -of each separate command for each I2C parameter. The I2C tool takes a different -approach, instead: The I2C configuration can be specified as a (potentially -long) sequence of command line arguments. - -These arguments, however, are _sticky_. They are sticky in the sense that once -you set the I2C parameter, that value will remain until it is reset with a new -value (or until you reset the board). - -### Environment Variables - -**Note** also that if environment variables are not disabled (by -`CONFIG_DISABLE_ENVIRON=y`), then these options may also be environment -variables. Environment variables must be preceded with the special character -`$`. For example, `PWD` is the variable that holds the current working directory -and so `$PWD` could be used as a command line argument. The use of environment -variables on the I2C tools command is really only useful if you wish to write -NSH scripts to execute a longer, more complex series of I2C commands. - -### Common Option Summary - -- `[-a addr]` is the I2C device address (hex). Default: `03` Current: `03` - - The `[-a addr]` sets the I2C device address. The valid range is `0x03` through - `0x77` (this valid range is controlled by the configuration settings - `CONFIG_I2CTOOL_MINADDR` and `CONFIG_I2CTOOL_MAXADDR`). If you are working - with the same device, the address needs to be set only once. - - All I2C address are 7-bit, hexadecimal values. - - **Note 1**: Notice in the `help` output above it shows both default value of the - I2C address (`03` hex) and the current address value (also `03` hex). - - **Note 2**: Sometimes I2C addresses are represented as 8-bit values (with bit zero - indicating a read or write operation). The I2C tool uses a 7-bit - representation of the address with bit 7 unused and no read/write indication - in bit 0. Essentially, the 7-bit address is like the 8-bit address shifted - right by 1. - - **Note 3**: Most I2C bus controllers will also support 10-bit addressing. That - capability has not been integrated into the I2C tool as of this writing. - -- `[-b bus]` is the I2C bus number (decimal). Default: `1` Current: `1` - - Most devices support multiple I2C devices and also have unique bus numbering. - This option identifies which bus you are working with now. The valid range of - bus numbers is controlled by the configuration settings - `CONFIG_I2CTOOL_MINBUS` and `CONFIG_I2CTOOL_MAXBUS`. - - The bus numbers are small, decimal numbers. - -- `[-r regaddr]` is the I2C device register address (hex). Default: `00` - Current: `00` - - The I2C set and get commands will access registers on the I2C device. This - option selects the device register address (sometimes called the sub-address). - This is an 8-bit hexadecimal value. The maximum value is determined by the - configuration setting `CONFIG_I2CTOOL_MAXREGADDR`. - -- `[-w width] `is the data width (8 or 16 decimal). Default: `8` Current: `8` - - Device register data may be 8-bit or 16-bit. This options selects one of those - two data widths. - -- `[-s|n]`, send/don't send start between command and data. Default: `-n` - Current: `-n` - - This determines whether or not there should be a new I2C START between sending - of the register address and sending/receiving of the register data. - -- `[-i|j]`, Auto increment|don't increment `regaddr` on repetitions. Default: - `NO` Current: `NO` - - On commands that take a optional number of repetitions, the option can be used - to temporarily increment the `regaddr` value by one on each repetition. - -- `[-f freq]` I2C frequency. Default: `400000` Current: `400000` - - The `[-f freq]` sets the frequency of the I2C device. - -## Command Summary - -We have already seen the I2C help (or `?`) commands above. This section will -discuss the remaining commands. - -### List buses: `bus [OPTIONS]` - -This command will simply list all of the configured I2C buses and indicate which -are supported by the driver and which are not: - -``` -BUS EXISTS? -Bus 1: YES -Bus 2: NO -``` - -The valid range of bus numbers is controlled by the configuration settings -`CONFIG_I2CTOOL_MINBUS` and `CONFIG_I2CTOOL_MAXBUS`. - -### List devices: `dev [OPTIONS] ` - -The `dev` command will attempt to identify all of the I2C devices on the -selected bus. The `` and `` arguments are 7-bit, hexadecimal I2C -addresses. This command will examine a range of addresses beginning with -`` and continuing through ``. It will request the value of register -address zero from each device. - -The register address of zero is always used by default. The previous _sticky_ -register address is ignored. Some devices may not respond to ergister address -zero, however. To work around this, you can provide a new _sticky_ register -address on the command as an option to the 'dev' command. Then that new _sticky_ -register address will be used instead of the address zero. - -If the device at an I2C address responds to the read request, then the `dev` -command will display the I2C address of the device. If the device does not -respond, this command will display `--`. The resulting display looks like: - -```shell -nsh> i2c dev 03 77 -``` - -``` - 0 1 2 3 4 5 6 7 8 9 a b c d e f -00: -- -- -- -- -- -- -- -- -- -- -- -- -- -10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -40: -- -- -- -- -- -- -- -- -- 49 -- -- -- -- -- -- -50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -70: -- -- -- -- -- -- -- -- -``` - -Warnings: -- The I2C dev command may have bad side effects on certain I2C devices. For - example, if could cause data loss in an EEPROM device. -- The I2C dev command also depends upon the underlying behavior of the I2C - driver. How does the driver respond to addressing failures? - -### Read register: `get [OPTIONS]` - -This command will read the value of the I2C register using the selected I2C -parameters in the common options. No other arguments are required. - -This command with write the 8-bit address value then read an 8- or 16-bit data -value from the device. Optionally, it may re-start the transfer before obtaining -the data. - -An optional `` argument can be supplied to repeat the read -operation an arbitrary number of times (up to 2 billion). If auto-increment is -select (`-i`), then the register address will be temporarily incremented on each -repetitions. The increment is temporary in the since that it will not alter the -_sticky_ value of the register address. - -On success, the output will look like the following (the data value read will be -shown as a 4-character hexadecimal number if the 16-bit data width option is -selected). - -``` -READ Bus: 1 Addr: 49 Subaddr: 04 Value: 96 -``` - -All values (except the bus numbers) are hexadecimal. - -### Write register: `set [OPTIONS] ` - -This command will write a value to an I2C register using the selected I2C -parameters in the common options. The value to write must be provided as the -final, hexadecimal value. This value may be an 8-bit value (in the range -`00`-`ff`) or a 16-bit value (in the range `0000`-`ffff`), depending upon the -selected data width. - -This command will write the 8-bit address value then write the 8- or 16-bit data -value to the device. Optionally, it may re-start the transfer before writing the -data. - -An optional `` argument can be supplied to repeat the write -operation an arbitrary number of times (up to 2 billion). If auto-increment is -select (`-i`), then the register address will be temporarily incremented on each -repetitions. The increment is temporary in the since that it will not alter the -_sticky_ value of the register address. - -On success, the output will look like the following (the data value written will -be shown as a 4-character hexadecimal number if the 16-bit data width option is -selected). - -``` -WROTE Bus: 1 Addr: 49 Subaddr: 04 Value: 96 -``` - -All values (except the bus numbers) are hexadecimal. - -### Verify access: `verf [OPTIONS] []` - - -This command combines writing and reading from an I2C device register. It will -write a value to an will write a value to an I2C register using the selected I2C -parameters in the common options just as described for tie `set` command. Then -this command will read the value back just as described with the `get` command. -Finally, this command will compare the value read and against the value written -and emit an error message if they do not match. - -If no value is provided, then this command will use the register address itself -as the data, providing for a address-in-address test. - -An optional `` argument can be supplied to repeat the verify -operation an arbitrary number of times (up to 2 billion). If auto-increment is -select (`-i`), then the register address will be temporarily incremented on each -repetitions. The increment is temporary in the since that it will not alter the -`sticky` value of the register address. - -On success, the output will look like the following (the data value written will -be shown as a 4-character hexadecimal number if the 16-bit data width option is -selected). - -``` -VERIFY Bus: 1 Addr: 49 Subaddr: 04 Wrote: 96 Read: 92 FAILURE -``` - -All values (except the bus numbers) are hexadecimal. - -## I2C Build Configuration - -### NuttX Configuration Requirements - -The I2C tools requires the following in your NuttX configuration: - -1. Application configuration. - - Using `make menuconfig`, select the i2c tool. The following definition should - appear in your `.config` file: - - ```conf - CONFIG_SYSTEM_I2C=y - ``` - -2. Device-specific I2C driver support must be enabled: - - ```conf - CONFIG_I2C_DRIVER=y - ``` - - The I2C tool will then use the I2C character driver to access the I2C bus. - These devices will reside at `/dev/i2cN` where `N` is the I2C bus number. - - **Note**: The I2C driver `ioctl` interface is defined in - `include/nuttx/i2c/i2c_master.h`. - -### I2C Tool Configuration Options - -The default behavior of the I2C tool can be modified by the setting the options -in the NuttX configuration. This configuration is the `defconfig` file in your -configuration directory that is copied to the NuttX top-level directory as -`.config` when NuttX is configured. - -- `CONFIG_NSH_BUILTIN_APPS` – Build the tools as an NSH built-in command. -- `CONFIG_I2CTOOL_MINBUS` – Smallest bus index supported by the hardware - (default `0`). -- `CONFIG_I2CTOOL_MAXBUS` – Largest bus index supported by the hardware - (default `3`). -- `CONFIG_I2CTOOL_MINADDR` – Minimum device address (default: `0x03`). -- `CONFIG_I2CTOOL_MAXADDR` – Largest device address (default: `0x77`). -- `CONFIG_I2CTOOL_MAXREGADDR` – Largest register address (default: `0xff`). -- `CONFIG_I2CTOOL_DEFFREQ` – Default frequency (default: `4000000`). diff --git a/system/libuv/README.md b/system/libuv/README.md deleted file mode 100644 index 9d853f207..000000000 --- a/system/libuv/README.md +++ /dev/null @@ -1,17 +0,0 @@ -# `libuv` - -Most features of libuv are supported by current port, except SIGPROF relative function (loop_configure). - -Nearly full libuv's test suite avaliable on NuttX, but some known case can't run on sim: - -* loop_update_time -* idle_starvation -* signal_multiple_loops -* signal_pending_on_close -* metrics_idle_time -* metrics_idle_time_thread -* metrics_idle_time_zero - -And some will cause crash by some reason: - -* fs_poll_ref diff --git a/system/nsh/README.md b/system/nsh/README.md deleted file mode 100644 index 8d3998b01..000000000 --- a/system/nsh/README.md +++ /dev/null @@ -1,50 +0,0 @@ -# System / `nsh` NuttShell (NSH) - -## Basic Configuration - -This directory provides an example of how to configure and use the NuttShell -(NSH) application. NSH is a simple shell application. NSH is described in its -own README located at `apps/nshlib/README.md`. This function is enabled with: - -```conf -CONFIG_SYSTEM_NSH=y -``` - -Applications using this example will need to provide an `defconfig` file in the -configuration directory with instruction to build the NSH library like: - -```conf -CONFIG_NSH_LIBRARY=y -``` - -## Other Configuration Requirements - -**Note**: If the NSH serial console is used, then following is also required to -build the `readline()` library: - -```conf -CONFIG_SYSTEM_READLINE=y -``` - -And if networking is included: - -```conf -CONFIG_NETUTILS_NETLIB=y -CONFIG_NETUTILS_DHCPC=y -CONFIG_NETDB_DNSCLIENT=y -CONFIG_NETUTILS_TFTPC=y -CONFIG_NETUTILS_WEBCLIENT=y -``` - -If the Telnet console is enabled, then the defconfig file should also include: - -```conf -CONFIG_NETUTILS_TELNETD=y -``` - -Also if the Telnet console is enabled, make sure that you have the following set -in the NuttX configuration file or else the performance will be very bad -(because there will be only one character per TCP transfer): - -- `CONFIG_STDIO_BUFFER_SIZE` - Some value `>= 64` -- `CONFIG_STDIO_LINEBUFFER=y` diff --git a/system/nxplayer/README.md b/system/nxplayer/README.md deleted file mode 100644 index a17730d53..000000000 --- a/system/nxplayer/README.md +++ /dev/null @@ -1,18 +0,0 @@ -# System / `nxplayer` NXPlayer - -``` -Author: Ken Pettit - Date: 11 Sept 2013 -``` - -This application implements a command-line media player which uses the NuttX -Audio system to play files (`mp3`, `wav`, etc.) from the file system. - -Usage: - -```shell -nxplayer -``` - -The application presents an command line for specifying player commands, such as -`play filename`, `pause`, `volume 50%`, etc. diff --git a/system/psmq/README.md b/system/psmq/README.md deleted file mode 100644 index 0e0d585a6..000000000 --- a/system/psmq/README.md +++ /dev/null @@ -1,61 +0,0 @@ -# System / `psmq` Publish Subscribe Message Queue - -`psmq` is publish subscribe message queue. It's a set of programs and libraries -to implement publish/subscribe way of inter-process communication on top of -POSIX message queue. - -Manuals, source code and more info at: https://psmq.bofc.pl - -Little demo using `psmqd` broker, `psmq_pub` and `psmq_sub`: - -Start broker and make it log to file - -``` -nsh> psmqd -b/brok -p/sd/psmqd/psmqd.log & -``` - -Start subscribe thread that will read all messages send on `/can/*` and -`/adc/*` topic, and dump all readings to file - -``` -nsh> psmq_sub -n/sub -b/brok -t/can/* -t/adc/* -o/sd/psmq-sub/can.log & -n/connected to broker /brok -n/subscribed to: /can/* -n/subscribed to: /adc/* -n/start receiving data -n/reply timeout set 100 -``` - -Publish some messages - -``` -nsh> psmq_pub -b/brok -t/can/engine/rpm -m50 -nsh> psmq_pub -b/brok -t/adc/volt -m30 -nsh> psmq_pub -b/brok -t/can/room/10/temp -m23 -nsh> psmq_pub -b/brok -t/pwm/fan1/speed -m300 -``` - -Check out subscribe thread logs - -``` -nsh> cat /sd/psmq-sub/can.log -``` - -``` -[2021-05-23 17:53:59] p:0 l: 3 /can/engine/rpm 50 -[2021-05-23 17:53:59] p:0 l: 3 /adc/volt 30 -[2021-05-23 17:53:59] p:0 l: 3 /can/room/10/temp 23 -``` - -As you can see `/pwm/fan1/speed` hasn't been received by subscribe thread, -since we didn't subscribe to it. - -Content: - -- `psmqd` – broker, relays messages between clients. -- `psmq_sub` – listens to specified topics, can be used as logger for - communication (optional). -- `psmq_pub` – publishes messages directly from shell. Can send binary data, but - requires pipes, so on nuttx it can only send ASCII. -- `libpsmq` – library used to communicate with the broker and send/receive - messages. diff --git a/system/spi/README.md b/system/spi/README.md deleted file mode 100644 index 2e6e3c5af..000000000 --- a/system/spi/README.md +++ /dev/null @@ -1,246 +0,0 @@ -# System / `spi` SPI Tool - -The I2C tool provides a way to debug SPI related problems. This README file will -provide usage information for the SPI tools. - -## Contents - -- System Requirements - - SPI Driver - - Configuration Options -- Help -- Common Line Form -- Common Command Options - - _Sticky_ Options - - Environment variables - - Common Option Summary -- Command summary - - `bus` - - `dev` - - `get` - - `set` - - `verf` -- I2C Build Configuration - - NuttX Configuration Requirements - - I2C Tool Configuration Options - -## System Requirements - -The SPI tool is designed to be implemented as a NuttShell (NSH) add-on. Read the -`apps/nshlib/README.md` file for information about add-ons. - -### Configuration Options - -- `CONFIG_NSH_BUILTIN_APPS` – Build the tools as an NSH built-in command. -- `CONFIG_SPITOOL_MINBUS` – Smallest bus index supported by the hardware - (default `0`). -- `CONFIG_SPITOOL_MAXBUS` – Largest bus index supported by the hardware - (default `3`). -- `CONFIG_SPITOOL_DEFFREQ` – Default frequency (default: `40000000`). -- `CONFIG_SPITOOL_DEFMODE` – Default mode, where - ``` - 0 = CPOL=0, CPHA=0 - 1 = CPOL=0, CPHA=1 - 2 = CPOL=1, CPHA=0 - 3 = CPOL=1, CPHA=1 - ``` -- `CONFIG_SPITOOL_DEFWIDTH` – Default bit width (default `8`). -- `CONFIG_SPITOOL_DEFWORDS` – Default number of words to exchange (default `1`). - -## Help - -The SPI tools supports some help output. That help output can be view by -entering either: - -``` -nsh> spi help -``` - -or - -``` -nsh> spi ? -``` - -Here is an example of the help output. I shows the general form of the command -line, the various SPI commands supported with their unique command line options, -and a more detailed summary of the command SPI command options. - -``` -nsh> Usage: spi [arguments] - -Where is one of: - - Show help : ? - List buses : bus - SPI Exchange : exch [OPTIONS] [] - Show help : help - -Where common _sticky_ OPTIONS include: - [-b bus] is the SPI bus number (decimal). Default: 0 Current: 2 - [-f freq] SPI frequency. Default: 4000000 Current: 4000000 - [-m mode] Mode for transfer. Default: 0 Current: 0 - [-u udelay] Delay after transfer in uS. Default: 0 Current: 0 - [-w width] Width of bus. Default: 8 Current: 8 - [-x count] Words to exchange. Default: 1 Current: 4 -``` - -**Notes**: - -- An environment variable like $PATH may be used for any argument. -- Arguments are _sticky_. For example, once the SPI address is specified, that - address will be re-used until it is changed. - -**Warning**: - -- The SPI commands may have bad side effects on your SPI devices. Use only at - your own risk. - -## Command Line Form - -The SPI is started from NSH by invoking the `spi` command from the NSH command -line. The general form of the `spi` command is: - -```shell -spi [arguments] -``` - -Where `` is a _sub-command_ and identifies one SPI operation supported by -the tool. `[arguments]` represents the list of arguments needed to perform the -SPI operation. Those arguments vary from command to command as described below. -However, there is also a core set of common `OPTIONS` supported by all commands. -So perhaps a better representation of the general SPI command would be: - -```shell -i2c [OPTIONS] [arguments] -``` - -Where `[OPTIONS]` represents the common options and and arguments represent the -operation-specific arguments. - -## Common Command Options - -### _Sticky_ Options - -In order to interact with SPI devices, there are a number of SPI parameters that -must be set correctly. One way to do this would be to provide to set the value -of each separate command for each SPI parameter. The SPI tool takes a different -approach, instead: The SPI configuration can be specified as a (potentially -long) sequence of command line arguments. - -These arguments, however, are _sticky_. They are sticky in the sense that once -you set the SPI parameter, that value will remain until it is reset with a new -value (or until you reset the board). - -### Environment Variables - -**Note** also that if environment variables are not disabled (by -`CONFIG_DISABLE_ENVIRON=y`), then these options may also be environment -variables. Environment variables must be preceded with the special character -`$`. For example, `PWD` is the variable that holds the current working directory -and so `$PWD` could be used as a command line argument. The use of environment -variables on the I2C tools command is really only useful if you wish to write -NSH scripts to execute a longer, more complex series of SPI commands. - -### Common Option Summary - -- `[-b bus]` is the SPI bus number (decimal). Default: `0` - - Which SPI bus to commiuncate on. The bus must have been initialised as a - character device in the config in the form `/dev/spiX` (e.g. `/dev/spi2`). - - The valid range of bus numbers is controlled by the configuration settings - `CONFIG_SPITOOL_MINBUS` and `CONFIG_SPITOOL_MAXBUS`. - - The bus numbers are small, decimal numbers. - -- `[-m mode]` SPI Mode for transfer. - - Which of the available SPI modes is to be used. Options are; - - ``` - 0 = CPOL=0, CPHA=0 - 1 = CPOL=0, CPHA=1 - 2 = CPOL=1, CPHA=0 - 3 = CPOL=1, CPHA=1 - ``` - -- `[-u udelay]` Delay after transfer in uS. Default: `0` - - Any extra delay to be provided after the transfer. Not normally needed from - the command line. - -- `[-x count]` Words to exchange Default: `1` - - The number of words to be transited over the bus. For sanitys sake this is - limited to a relatively small number (`40` by default). Any data on the - command line is sent first, padded by `0xFF`'s while any remaining data are - received. - -- `[-w width]` is the data width (varies according to target). Default: `8` - - Various SPI devices support different data widths. This option is untested. - -- `[-f freq]` I2C frequency. Default: `4000000` Current: `4000000` - - The `[-f freq]` sets the frequency of the SPI device. The default is very - conservative. - -## Command Summary - -### List buses: `bus [OPTIONS]` - -This command will simply list all of the configured SPI buses and indicate which -are supported by the driver and which are not: - -``` -BUS EXISTS? -Bus 1: YES -Bus 2: NO -``` - -The valid range of bus numbers is controlled by the configuration settings -`CONFIG_SPITOOL_MINBUS` and `CONFIG_SPITOOL_MAXBUS`. - -### Exchange data: `exch [OPTIONS] ` - -This command triggers an SPI transfer, returning the data back from the far end. -As an example (with MOSI looped back to MISO); - -```shell -nsh> spi exch -b 2 -x 4 aabbccdd -``` - -``` -Received: AA BB CC DD -``` - -Note that the `TX Data` are always specified in hex, and are always two digits -each, case insensitive. - -## I2C Build Configuration - -### NuttX Configuration Requirements - -The SPI tools requires the following in your NuttX configuration: - -1. Application configuration. - - Using `make menuconfig`, select the SPI tool. The following definition should - appear in your `.config` file: - - ```conf - CONFIG_SYSTEM_SPI=y - ``` - -2. Device-specific SPI driver support must be enabled: - - ```conf - CONFIG_SPI_DRIVER=y - ``` - - The SPI tool will then use the SPI character driver to access the SPI bus. - These devices will reside at `/dev/spiN` where `N` is the I2C bus number. - - **Note**: The SPI driver `ioctl` interface is defined in - `include/nuttx/spi/spi.h`. diff --git a/system/termcurses/README.md b/system/termcurses/README.md deleted file mode 100644 index 9a23cf9b0..000000000 --- a/system/termcurses/README.md +++ /dev/null @@ -1,50 +0,0 @@ -# System / `termcurses` Termcurses - -Terminal emulation library for NuttX - -``` -Author: Ken Pettit - Date: 2018-2019 -``` - -The Termcurses library provides terminal emulation support for performing common -screen actions such as cursor movement, foreground / background color control -and keyboard escape sequence mapping. The initial release supports only `vt100` -/ `ansi` terminal types, but the library architecture has an extensible -interface to allow support for additional emulation types if needed. - -The library can be used standalone or in conjunction with the -`apps/graphics/pdcurses` libraries. The pdcurses libraries have been updated -with a _termcurses_ config option which fully integrates the termcurses library -automatically. - -## Usage - -To use the termcurses library, the routines must be initialized by calling the -`termcurses_initterm()` function. This routine accepts a terminal type string -identifying the type of terminal emulation support requested. If a `NULL` -pointer is passed, then the routine will check for a `TERM` environment variable -and set the terminal type based on that string. If the emulation type still -cannot be determined, the routine will default to `vt100` emulation type. - -Upon successful initialization, the `termcurses_initterm()` function will -allocate an new terminal context which must be passed with all future termcurses -library functions. When this context is no longer needed, the -`termcurses_deinitterm()` routine should be called for proper freeing and -terminal teardown. - -## Use with `telnetd` - -When using termcurses with the telnet daemon, the telnet config option -`CONFIG_TELNET_SUPPORT_NAWS` should be enabled. This option adds code to the -telnet library for terminal size negotiation. Without this option, the telnet -routines have no concept of the terminal size, and therefore the termcurses -routines must default to `80x24` screen mode. - -## Use with `pdcurses` - -When using the pdcurses termcurses support (i.e you have enabled both the -`CONFIG_PDCURSES` and `CONFIG_TERMCURSES` options),, the pdcurses input device -should be selected to be `TERMINPUT` (i.e. set `CONFIG_PDCURSES_TERMINPUT=y`). -This causes the pdcurses keyboard input logic to use `termcurses_getkeycode()` -routine for curses input. diff --git a/system/trace/README.md b/system/trace/README.md deleted file mode 100644 index 3067cd046..000000000 --- a/system/trace/README.md +++ /dev/null @@ -1,4 +0,0 @@ -System / `trace` Task Tracer -============================ - -See https://nuttx.apache.org/docs/latest/guides/tasktraceuser.html diff --git a/system/usbmsc/README.md b/system/usbmsc/README.md deleted file mode 100644 index da85f8bbc..000000000 --- a/system/usbmsc/README.md +++ /dev/null @@ -1,85 +0,0 @@ -# System / `usbmsc` USB storage driver - -This add-on registers a block device driver, then exports the block the device -using the USB storage class driver. In order to use this add-on, your -board-specific logic must provide the function: - -```c -void board_usbmsc_initialize(void); -``` - -This function will be called by the `system/usbmsc` indirectly via the `boardctl` -`BOARDIOC_USBDEV_CONTROL` command in order to do the actual registration of the -block device drivers. For examples of the implementation of -`board_usbmsc_initialize()` see -`boards/arm/lpc214x/mcu123-lpc214x/src/up_usbmsc.c` or -`boards/arm/stm32/stm3210e-eval/src/usbmsc.c`. - -Configuration options: - -- `CONFIG_NSH_BUILTIN_APPS` – This add-on can be built as two NSH _built-in_ - commands if this option is selected: `msconn` will connect the USB mass - storage device; `msdis` will disconnect the USB storage device. - -- `CONFIG_BOARDCTL` – Enables the `boardctl()` interfaces. - -- `CONFIG_BOARDCTL_USBDEVCTRL` – Enables the `BOARDIOC_USBDEV_CONTROL` - `boardctl()` command. - -- `CONFIG_SYSTEM_USBMSC_NLUNS` – Defines the number of logical units (LUNs) - exported by the USB storage driver. Each LUN corresponds to one exported block - driver (or partition of a block driver). May be `1`, `2`, or `3`. Default is - `1`. - -- `CONFIG_SYSTEM_USBMSC_DEVMINOR1` – The minor device number of the block driver - for the first LUN. For example, `N` in `/dev/mmcsdN`. Used for registering the - block driver. Default is zero. - -- `CONFIG_SYSTEM_USBMSC_DEVPATH1` – The full path to the registered block - driver. Default is `/dev/mmcsd0` - -- `CONFIG_SYSTEM_USBMSC_DEVMINOR2` and `CONFIG_SYSTEM_USBMSC_DEVPATH2` - Similar parameters that would have to be provided if - `CONFIG_SYSTEM_USBMSC_NLUNS` is `2` or `3`. No defaults. - -- `CONFIG_SYSTEM_USBMSC_DEVMINOR3` and `CONFIG_SYSTEM_USBMSC_DEVPATH3` - Similar parameters that would have to be provided if - `CONFIG_SYSTEM_USBMSC_NLUNS` is `3`. No defaults. - -- `CONFIG_SYSTEM_USBMSC_DEBUGMM` – Enables some debug tests to check for memory - usage and memory leaks. - -If `CONFIG_USBDEV_TRACE` is enabled (or `CONFIG_DEBUG_FEATURES` and -`CONFIG_DEBUG_USB`), then the code will also manage the USB trace output. The -amount of trace output can be controlled using: - -- `CONFIG_SYSTEM_USBMSC_TRACEINIT` – Show initialization events. -- `CONFIG_SYSTEM_USBMSC_TRACECLASS` – Show class driver events. -- `CONFIG_SYSTEM_USBMSC_TRACETRANSFERS` – Show data transfer events. -- `CONFIG_SYSTEM_USBMSC_TRACECONTROLLER` – Show controller events. -- `CONFIG_SYSTEM_USBMSC_TRACEINTERRUPTS` – Show interrupt-related events. - -Error results are always shown in the trace output - -**Note 1**: When built as an NSH add-on command (`CONFIG_NSH_BUILTIN_APPS=y`), -Caution should be used to assure that the SD drive (or other storage device) is -not in use when the USB storage device is configured. Specifically, the SD -driver should be unmounted like: - -```shell -nsh> mount -t vfat /dev/mmcsd0 /mnt/sdcard # Card is mounted in NSH -... -nsh> umount /mnd/sdcard # Unmount before connecting USB!!! -nsh> msconn # Connect the USB storage device -... -nsh> msdis # Disconnect USB storate device -nsh> mount -t vfat /dev/mmcsd0 /mnt/sdcard # Restore the mount -``` - -Failure to do this could result in corruption of the SD card format. - -**Note 2**: This add-on used internal USB device driver interfaces. As such, it -relies on internal OS interfaces that are not normally available to a user-space -program. As a result, this add-on cannot be used if a NuttX is built as a -protected, supervisor kernel (`CONFIG_BUILD_PROTECTED` or -`CONFIG_BUILD_KERNEL`). diff --git a/system/ymodem/README.md b/system/ymodem/README.md deleted file mode 100644 index f7bf687de..000000000 --- a/system/ymodem/README.md +++ /dev/null @@ -1,51 +0,0 @@ -# Introduce - -This is [ymodem protocal](http://pauillac.inria.fr/~doligez/zmodem/ymodem.txt). -According to it, the sb rb application is realized, which is used to send files and receive files respectively - -# Usage - -## Common Usage - -In the ubuntu system, lszrz needs to be installed, can use `sudo apt install lszrz`. -Use minicom to communicate with the board. - - -## Advanced Usage - -In order to achieve a faster transmission speed, -I added a specific HEADER `STC` to the YMODEM protocol to represent the custom length. -Using the `sb` and `rb` commands on the board, you can use the `-k` option to set the length -of the custom packet, and the unit is KB. Therefore, you need to use `sbrb.py` for file transfer, -and you need `sbrb.py` -k to set the same length as the board. According to my test, -when using -k 32, it can reach 93% of the baud rate, -and is fully compatible with the original ymodem protocol. -First, you need to add a soft link to sbrb.py, for example `sudo ln -s /home//...//apps/system/ymodem/sbrb.py /usr/bin` -and then sbrb.py can be configured into minicom.` z o` then chose `File transfer protocols` and -crate two option cmd is 'sbrb.py -k 32'. like this - -| Name | Program | Name | U/D | FullScr | IO-Red. | Multi | -| ---- | ------- | ---- | --- | ------- | ------- | ----- | -| ymodem-k | sbrb.py -k 32 | Y | U | N | Y | Y | -| ymodem-k | sbrb.py -k 32 | N | D | N | Y | Y | - -usb `sb -k 32` or `rb -k 32` for file transfer on board. - -## Sendfile to pc - -use sb command like this `nsh> sb /tmp/test.c ...`, this command support send multiple files together -then use ` , r` chose `ymodem` to receive board file. - -## Sendfile to board - -use rb cmd like this `nsh> rb`, this command support receive multiple files together -then use ` , s` chose `ymodem`, then chose what file need to send. - -## help - -can use `sb -h` or `rb -h` get help. - -# Debug - -Because the serial port is used for communication, the log is printed to the debug file -you can use `CONFIG_SYSTEM_YMODEM_DEBUGFILE_PATH` set debug file path. diff --git a/system/zmodem/README.md b/system/zmodem/README.md deleted file mode 100644 index a48f67b8f..000000000 --- a/system/zmodem/README.md +++ /dev/null @@ -1,280 +0,0 @@ -# System / `zmodem` - -## Contents - -- Buffering Notes - - Hardware Flow Control - - RX Buffer Size - - Buffer Recommendations -- Using NuttX ZModem with a Linux Host - - Sending Files from the Target to the Linux Host PC - - Receiving Files on the Target from the Linux Host PC -- Building the ZModem Tools to Run Under Linux -- Status - -## Buffering Notes - -### Hardware Flow Control - -Hardware flow control must be enabled in serial drivers in order to prevent data -overrun. However, in the most NuttX serial drivers, hardware flow control only -protects the hardware RX FIFO: Data will not be lost in the hardware FIFO but -can still be lost when it is taken from the FIFO. We can still overflow the -serial driver's RX buffer even with hardware flow control enabled! That is -probably a bug. But the workaround solution that I have used is to use lower -data rates and a large serial driver RX buffer. - -Those measures should be unnecessary if buffering and hardware flow control are -set up and working correctly. - -### Software Flow Control - -The ZModem protocol has `XON/XOFF` flow control built into it. The protocol -permits `XON` or `XOFF` characters placed at certain parts of messages. If -software flow control is enabled on the receiving end it will consume the `XON`s -and `XOFF`s. Otherwise they will be ignored in the data by the ZModem logic. - -NuttX, however, does not implement `XON/XOFF` flow control so these do nothing. -On NuttX you will have to use hardware flow control in most cases. - -The `XON`/`XOFF` controls built into ZModem could be used if you enabled -software flow control in the host. But that would only work in one direction: If -would prevent the host from overrunning the the target Rx buffering. So you -should be able to do host-to-target software flow control. But there would still -be no target-to-host flow control. That might not be an issue because the host -is usually so much faster than that target. - -### RX Buffer Size - -The ZModem protocol supports a message that informs the file sender of the -maximum size of data that you can buffer (`ZRINIT`). However, my experience is -that the Linux sz ignores this setting and always sends file data at the maximum -size (`1024`) no matter what size of buffer you report. That is unfortunate -because that, combined with the possibilities of data overrun mean that you must -use quite large buffering for ZModem file receipt to be reliable (none of these -issues effect sending of files). - -### Buffer Recommendations - -Based on the limitations of NuttX hardware flow control and of the Linux sz -behavior, I have been testing with the following configuration (assuming `UART1` -is the ZModem device): - -1) This setting determines that maximum size of a data packet frame: - - ```conf - CONFIG_SYSTEM_ZMODEM_PKTBUFSIZE=1024 - ``` - -2) Input Buffering. If the input buffering is set to a full frame, then data - overflow is less likely. - - ```conf - CONFIG_UART1_RXBUFSIZE=1024` - ``` - -3) With a larger driver input buffer, the ZModem receive I/O buffer can be - smaller: - - ```conf - CONFIG_SYSTEM_ZMODEM_RCVBUFSIZE=256 - ``` - -4) Output buffering. Overrun cannot occur on output (on the NuttX side) so there - is no need to be so careful: - - ```conf - CONFIG_SYSTEM_ZMODEM_SNDBUFSIZE=512 - CONFIG_UART1_TXBUFSIZE=256 - ``` - -## Using NuttX ZModem with a Linux Host - -### Sending Files from the Target to the Linux Host PC - -The NuttX ZModem commands have been verified against the rzsz programs running -on a Linux PC. To send a file to the PC, first make sure that the serial port is -configured to work with the board (Assuming you are using 9600 baud for the data -transfers - high rates may result in data overruns): - -```bash -$ sudo stty -F /dev/ttyS0 9600 # Select 9600 BAUD -$ sudo stty -F /dev/ttyS0 crtscts # Enables CTS/RTS handshaking * -$ sudo stty -F /dev/ttyS0 raw # Puts the TTY in raw mode -$ sudo stty -F /dev/ttyS0 # Show the TTY configuration -``` - -\* Only if hardware flow control is enabled. - -Start `rz` on the Linux host (using `/dev/ttyS0` as an example): - -```bash -$ sudo rz < /dev/ttyS0 > /dev/ttyS0 -``` - -You can add the `rz -v` option multiple times, each increases the level of debug -output. If you want to capture the Linux `rz` output, then re-direct `stderr` to -a log file by adding `2>rz.log` to the end of the `rz` command. - -**Note**: The NuttX ZModem does sends `rz\n` when it starts in compliance with -the ZModem specification. On Linux this, however, seems to start some other, -incompatible version of `rz`. You need to start `rz` manually to make sure that -the correct version is selected. You can tell when this evil `rz`/`sz` has -inserted itself because you will see the `^` (`0x5e`) character replacing the -standard ZModem `ZDLE` character (`0x19`) in the binary data stream. - -If you don't have the `rz` command on your Linux box, the package to install -`rzsz` (or possibly `lrzsz`). - -Then on the target (using `/dev/ttyS1` as an example). - -``` -nsh> sz -d /dev/ttyS1 -``` - -Where filename is the full path to the file to send (i.e., it begins with the -`/` character). `/dev/ttyS1` or whatever device you select **must** support -Hardware flow control in order to throttle therates of data transfer to fit -within the allocated buffers. - -### Receiving Files on the Target from the Linux Host PC - -**Note**: There are issues with using the Linux `sz` command with the NuttX `rz` -command. See _Status_ below. It is recommended that you use the NuttX `sz` -command on Linux as described in the next paragraph. - -To send a file to the target, first make sure that the serial port on the host -is configured to work with the board (Assuming that you are using `9600` baud -for the data transfers - high rates may result in data overruns): - -```bash -$ sudo stty -F /dev/ttyS0 9600 # Select 9600 (or other) BAUD -$ sudo stty -F /dev/ttyS0 crtscts # Enables CTS/RTS handshaking * -$ sudo stty -F /dev/ttyS0 raw # Puts the TTY in raw mode -$ sudo stty -F /dev/ttyS0 # Show the TTY configuration -``` - -\* Only is hardware flow control is enabled. - -Start `rz` on the on the target. Here, in this example, we are using -`/dev/ttyS1` to perform the transfer - -```shell -nsh> rz -d /dev/ttyS1 -``` - -`/dev/ttyS1` or whatever device you select **must** support Hardware flow -control in order to throttle therates of data transfer to fit within the -allocated buffers. - -Then use the `sz` command on Linux to send the file to the target: - -```bash -$ sudo sz [-l nnnn] [-w nnnn] /dev/ttyS0 -``` - -Where `` is the file that you want to send. If `-l nnnn` and `-w nnnn` -is not specified, then there will likely be packet buffer overflow errors. -`nnnn` should be set to a value less than or equal to -`CONFIG_SYSTEM_ZMODEM_PKTBUFSIZE`. - -The resulting file will be found where you have configured the ZModem -**sandbox** via `CONFIG_SYSTEM_ZMODEM_MOUNTPOINT`. - -You can add the `sz -v` option multiple times, each increases the level of debug -output. If you want to capture the Linux `sz` output, then re-direct `stderr` to -a log file by adding `2>sz.log` to the end of the `sz` command. - -If you don't have the sz command on your Linux box, the package to install -`rzsz` (or possibly `lrzsz`). - -## Building the ZModem Tools to Run Under Linux - -Build support has been added so that the NuttX ZModem implementation can be -executed on a Linux host PC. This can be done by - -- Change to the `apps/systems/zmodem` directory -- Make using the special makefile, `Makefile.host` - -**Notes**: - -1. `TOPDIR` and `APPDIR` must be defined on the make command line: `TOPDIR` is - the full path to the `nuttx/` directory; `APPDIR` is the full path to the - `apps/` directory. For example, if you installed nuttx at - `/home/me/projects/nuttx` and apps at `/home/me/projects/apps`, then the - correct make command line would be: - - ```bash - make -f Makefile.host TOPDIR=/home/me/projects/nuttx APPDIR=/home/me/projects/apps - ``` - -2. Add `CONFIG_DEBUG_FEATURES=1` to the make command line to enable debug output -3. Make sure to clean old target `.o` files before making new host `.o` files. - -This build is has been verified as of `2013-7-16` using Linux to transfer files -with an Olimex LPC1766STK board. It works great and seems to solve all of the -problems found with the Linux `sz`/`rz` implementation. - -## Status - -- `2013-7-15`: Testing against the Linux `rz`/`sz` commands. - - I have tested with the `boards/arm/lpc17xx_40xx/olimex-lpc1766stk` - configuration. I have been able to send large and small files with the target - `sz` command. I have been able to receive small files, but there are problems - receiving large files using the Linux `sz` command: The Linux `sz` does not - obey the buffering limits and continues to send data while `rz` is writing the - previously received data to the file and the serial driver's RX buffer is - overrun by a few bytes while the write is in progress. As a result, when it - reads the next buffer of data, a few bytes may be missing. The symptom of this - missing data is a CRC check failure. - - Either (1) we need a more courteous host application, or (2) we need to - greatly improve the target side buffering capability! - - My thought now is to implement the NuttX `sz` and `rz` commands as PC side - applications as well. Matching both sides and obeying the handshaking will - solve the issues. Another option might be to fix the serial driver hardware - flow control somehow. - -- `2013-7-16`. More Testing against the Linux `rz`/`sz` commands. - - I have verified that with debug off and at lower serial BAUD (`2400`), the - transfers of large files succeed without errors. I do not consider this a - _solution_ to the problem. I also found that the LPC17xx hardware flow control - caused strange hangs; ZModem works better with hardware flow control disabled - on the LPC17xx. - - At this lower BAUD, RX buffer sizes could probably be reduced; Or perhaps the - BAUD could be increased. My thought, however, is that tuning in such an - unhealthy situation is not the approach: The best thing to do would be to use - the matching NuttX sz on the Linux host side. - -- `2013-7-16`. More Testing against the NuttX `rz`/`sz` on Both Ends. - - The NuttX `sz`/`rz` commands have been modified so that they can be built and - executed under Linux. In this case, there are no transfer problems at all in - either direction and with large or small files. This configuration could - probably run at much higher serial speeds and with much smaller buffers - (although that has not been verified as of this writing). - -- `2018-5-27` - - Updates to checksum calculations. Verified correct operation with hardware - flow control using the `olimex-stm32-p407/zmodem` configuration. Only the - host-to-target transfer was verified. - - This was using the Linux `sz` utility. There appears to still be a problem - using the NuttX `sz` utility running on Linux. - -- `2018-5-27` - - Verified correct operation with hardware flow control using the - `olimex-stm32-p407/zmodem` configuration with target-to-host transfers was - verified. Again, there are issues remaining if I tried the NuttX `rz` utility - running on Linux. - -- `2018-6-26` - - With `-w nnnn` option, the host-to-target transfer can work reliably without - hardware flow control.