Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Convert README to MarkDown for GitHub automatic Rendering #18

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Convert README to MarkDown for GitHub automatic Rendering #18

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
107 changes: 64 additions & 43 deletions README.txt → README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@

M-Stack: Free USB Stack for PIC 16F, 18F, 24F, and 32MX Microcontrollers
==========================================================================
M-Stack: Free USB Stack for PIC 16F, 18F, 24F, and 32MX Microcontrollers
==========================================================================

About
======
Expand Down Expand Up @@ -40,7 +40,7 @@ creating a USB device.
Home
-----
The master web page for this project can be found at:
http://www.signal11.us/oss/m-stack/
http://www.signal11.us/oss/m-stack/

License
========
Expand Down Expand Up @@ -86,10 +86,12 @@ Getting Started
Downloading the Software
-------------------------
M-Stack's source code is currently hosted on Github at:
https://github.com/signal11/m-stack
https://github.com/signal11/m-stack

To get the latest version, run:
git clone https://github.com/signal11/m-stack.git
```
git clone https://github.com/signal11/m-stack.git
```

Documentation
--------------
Expand Down Expand Up @@ -131,48 +133,53 @@ The USB stack is supported by the following software:
* Microchip MPLAB X IDE

Note that the C18 compiler is not currently supported. There are some
#defines in the code for C18 because this project came from code that was
`#defines` in the code for C18 because this project came from code that was
originally done on a PIC18F4550 using C18. It has not yet been determined
whether a port to C18 will be made, as C18 has been deprecated by Microchip.
Further, C18 has some properties which make a port somewhat more difficult
than other compilers.

Building the Unit Test Firmware
--------------------------------
Open the MPLAB.X project in apps/unit_test in the MPLAB X IDE. Select a
Open the MPLAB.X project in `apps/unit_test` in the MPLAB X IDE. Select a
configuration and build. Make sure a supported compiler is installed.

Building the Test Software
---------------------------
The host_test/ directory contains Libusb-based test programs for testing the
The `host_test/` directory contains Libusb-based test programs for testing the
functionality of a USB device running the unit test firmware. Currently the
Libusb test software has only been tested Linux, but since its only
dependency is the cross-platform Libusb library, it is easily portable to
other operating systems on which Libusb is supported.

With Libusb installed, run "make" in the host_test/ directory to build the
With Libusb installed, run "make" in the `host_test/` directory to build the
test software.

Running the Test Software
--------------------------
./control_transfer_in [number_of_bytes]
* Execute an IN control transfer requesting number_of_bytes bytes
from the device. The data returned will be printed. The unit test
firmware supports control transfers up to 512 bytes.
./control_transfer_out [number_of_bytes]
* Execute an OUT control transfer sending number_of_bytes bytes
to the device. A message will be printed. The unit test
firmware supports control transfers up to 512 bytes.
./test [number_of_bytes]
* Send and then ask for number_of_bytes bytes on EP 1 OUT and EP 1
IN, respectively. The data is printed out. The unit test firmware
will support up to 128-bytes of this kind of operation.
./feature <clear>
* Set the Endpoint halt feature on Endpoint 1 IN. Passing the
"clear" parameter clears endpoint halt.
`./control_transfer_in [number_of_bytes]`
* Execute an IN control transfer requesting `number_of_bytes` bytes
from the device. The data returned will be printed. The unit test
firmware supports control transfers up to 512 bytes.

`./control_transfer_out [number_of_bytes]`
* Execute an OUT control transfer sending `number_of_bytes` bytes
to the device. A message will be printed. The unit test
firmware supports control transfers up to 512 bytes.

`./test [number_of_bytes]`
* Send and then ask for `number_of_bytes` bytes on EP 1 OUT and EP 1
IN, respectively. The data is printed out. The unit test firmware
will support up to 128-bytes of this kind of operation.

`./feature <clear>`
* Set the Endpoint halt feature on Endpoint 1 IN. Passing the
"clear" parameter clears endpoint halt.

Source Tree Structure
----------------------

```
(root)
|
+- usb/ <- USB stack software
Expand All @@ -189,9 +196,12 @@ Source Tree Structure
+- msc_test/ <- Mass Storage Class example
+- bootloader/ <- USB bootloader firmware and software
+- host_test/ <- Software applications to run from a PC Host
```

USB Stack Source Files
-----------------------

```
usb/src/usb.c - The implementation of the USB stack.
usb/src/usb_hal.h - Hardware abstraction layer (HAL) containing
differences specific to each platform.
Expand All @@ -204,9 +214,12 @@ usb/include/usb_ch9.h - Enums and structs from Chapter 9 of the USB
file from their usb_descriptors.c and from any file
which deals with control transfers.
usb/src/usb_hid.h - Enums, structs, and callbacks for the HID class
```

Application Source Files (Unit Test Example)
---------------------------------------------

```
apps/unit_test/main.c - Main program file
apps/unit_test/usb_config.h - USB stack configuration file. The USB
stack will include this file and use it
Expand All @@ -219,29 +232,32 @@ apps/unit_test/usb_descriptors.c - The application's descriptors. The
application's needs.
apps/hid_mouse/* - HID mouse example (same files as above)

```

Making Your Own Project
------------------------
The easiest way to create a project using M-Stack is to simply copy one of
the examples and modify it accordingly. Sometimes it's better though to do
things the hard way in order to understand better.

To create a new project, perform the following steps:

1. Create a new project with MPLAB X.
2. Copy and add the usb/ directory as a subdirectory of your project.
3. Add the usb/include directory to the include path of your project. (Note
2. Copy and add the `usb/` directory as a subdirectory of your project.
3. Add the `usb/include` directory to the include path of your project. (Note
that the include paths are relative to the Makefile. If you set up your
project like the examples, with an MPLAB.X/ subdirectory, you'll need to
add an additional ../ to the beginning of the include path).
4. Add . to the include path of your project (same note from #3 applies).
5. Copy a usb_config.h and a usb_descriptors.c file from one of the example
project like the examples, with an `MPLAB.X/` subdirectory, you'll need to
add an additional `../` to the beginning of the include path).
4. Add `.` to the include path of your project (same note from #3 applies).
5. Copy a`usb_config.h` and a `usb_descriptors.c` file from one of the example
projects into your main project directory.
6. Modify usb_config.h to match your desired device configuration.
7. Modify usb_descriptors.c to match your device configuration.
6. Modify `usb_config.h` to match your desired device configuration.
7. Modify `usb_descriptors.c` to match your device configuration.
8. If you're using a PIC16F/18F platform, add an interrupt handler similar
to one of the examples.
9. Reference main.c in one of the examples, and the Doxygen-generated
9. Reference `main.c` in one of the examples, and the Doxygen-generated
documentation to add your application logic.
10. Make sure to configure the MCU for your board (__CONFIG registers, etc.).
10. Make sure to configure the MCU for your board (`__CONFIG` registers, etc.).


Limitations
Expand All @@ -257,9 +273,10 @@ Future Plans
=============

The following features are on the horizon:
* Support for more specific MCUs
* dsPIC33E and PIC24E support
* Isochronous transfers

* Support for more specific MCUs
* dsPIC33E and PIC24E support
* Isochronous transfers


References
Expand All @@ -268,13 +285,17 @@ References
USB
----
USB Implementers Forum: http://www.usb.org

USB Specification, 2.0: http://www.usb.org/developers/docs

Jan Axelson's "USB Complete," 4th Edition: http://www.lvr.com/usbc.htm

Jan Axelson's online USB resources: http://www.lvr.com/usb.htm

Microchip PIC
--------------
Microchip Libraries for Applications: http://www.microchip.com/mla

Microchip MPLAB X: http://www.microchip.com/mplabx

Contacts
Expand All @@ -283,11 +304,11 @@ Contacts
Please contact Signal 11 Software directly for support or consulting help.
Sometime in the near future there will be a mailing list.

Alan Ott
Signal 11 Software
[email protected]
http://www.signal11.us
+1 407-222-6975
Alan Ott
Signal 11 Software
[email protected]
http://www.signal11.us
+1 407-222-6975

2013-04-26
2013-04-26
2013-05-20