diff --git a/README.txt b/README.md similarity index 80% rename from README.txt rename to README.md index dba1ca7..f75ec0d 100644 --- a/README.txt +++ b/README.md @@ -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,7 +133,7 @@ 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 @@ -139,40 +141,45 @@ 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 - * 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 ` + * 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,6 +232,8 @@ 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 @@ -226,22 +241,23 @@ 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,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 @@ -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 -alan@signal11.us -http://www.signal11.us -+1 407-222-6975 +Alan Ott +Signal 11 Software +alan@signal11.us +http://www.signal11.us ++1 407-222-6975 -2013-04-26 +2013-04-26 2013-05-20