remove system/xxx/README.md. Migrated to Documentation/applications/system
This commit is contained in:
raiden00pl
Xiang Xiao
parent
292b0cbc28
commit
4acad717fe
@ -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.
|
||||
@ -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 <cmd> [arguments]
|
||||
```
|
||||
|
||||
Where `<cmd>` 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
|
||||
@ -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.
|
||||
@ -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 <flash_block_device>
|
||||
```
|
||||
@ -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 <cmd> [arguments]
|
||||
Where <cmd> is one of:
|
||||
|
||||
Show help : ?
|
||||
List buses : bus
|
||||
List devices : dev [OPTIONS] <first> <last>
|
||||
Read register : get [OPTIONS] [<repetitions>]
|
||||
Show help : help
|
||||
Write register: set [OPTIONS] <value> [<repetitions>]
|
||||
Verify access : verf [OPTIONS] <value> [<repetitions>]
|
||||
|
||||
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 <cmd> [arguments]
|
||||
```
|
||||
|
||||
Where `<cmd>` 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 <cmd> [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] <first> <last>`
|
||||
|
||||
The `dev` command will attempt to identify all of the I2C devices on the
|
||||
selected bus. The `<first>` and `<last>` arguments are 7-bit, hexadecimal I2C
|
||||
addresses. This command will examine a range of addresses beginning with
|
||||
`<first>` and continuing through `<last>`. 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 `<repetitions>` 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] <value>`
|
||||
|
||||
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 `<repetitions>` 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] <value> [<repetitions>]`
|
||||
|
||||
|
||||
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 `<repetitions>` 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`).
|
||||
@ -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
|
||||
@ -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`
|
||||
@ -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.
|
||||
@ -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.
|
||||
@ -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 <cmd> [arguments]
|
||||
|
||||
Where <cmd> is one of:
|
||||
|
||||
Show help : ?
|
||||
List buses : bus
|
||||
SPI Exchange : exch [OPTIONS] [<hex senddata>]
|
||||
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 <cmd> [arguments]
|
||||
```
|
||||
|
||||
Where `<cmd>` 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 <cmd> [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] <Optional TX Data>`
|
||||
|
||||
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`.
|
||||
@ -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.
|
||||
@ -1,4 +0,0 @@
|
||||
System / `trace` Task Tracer
|
||||
============================
|
||||
|
||||
See https://nuttx.apache.org/docs/latest/guides/tasktraceuser.html
|
||||
@ -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`).
|
||||
@ -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/<name>/.../<nuttxwork>/apps/system/ymodem/sbrb.py /usr/bin`
|
||||
and then sbrb.py can be configured into minicom.`<Ctrl + a> 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 `<Ctrl + a> , 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 `<Ctrl + a> , 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.
|
||||
@ -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 <filename>
|
||||
```
|
||||
|
||||
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 <filename> [-l nnnn] [-w nnnn] </dev/ttyS0 >/dev/ttyS0
|
||||
```
|
||||
|
||||
Where `<filename>` 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.
|
||||
Loading…
x
Reference in New Issue
Block a user