-
Notifications
You must be signed in to change notification settings - Fork 96
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Convert README to MarkDown for GitHub automatic Rendering
Signed-off-by: Ekaitz Zárraga <[email protected]>
- Loading branch information
Ekaitz Zárraga
committed
Aug 25, 2016
1 parent
3868420
commit 367f0e4
Showing
1 changed file
with
63 additions
and
43 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 | ||
| ====== | ||
|
|
@@ -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 | ||
| ======== | ||
|
|
@@ -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 | ||
| -------------- | ||
|
|
@@ -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 | ||
|
|
@@ -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. | ||
|
|
@@ -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 | ||
|
|
@@ -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 | ||
|
|
@@ -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 | ||
|
|
@@ -268,8 +285,11 @@ 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 | ||
|
|
@@ -283,11 +303,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 | ||