Documentation / tutorial proposal

[Guest XORNOT]

Hi Everyone, I would like to propose a new documentation and tutorial project for the midibox.

My idea is to use the midibox hardware platform as a lab in order to write a series of tutorials on PIC programming, aimed specifically at the problems musicians are likely to be interested in. The problem for me is that MIOS has become so sophisticated as to be far too complex for a beginner to use as a springboard for PIC programming themselves. The hardware platform on the other hand is modular, clean, elegant, and well supported for hobbyists with fantastic boards available from Mike and Smash, etc. I believe that in the long run, it can only do us all good to have a growing number of capable coders and designers that believe in the open source approach Thorsten has embodied. However, I would sure rather be cutting my teetch on midi oriented projects and on a hardware platform I will use than on some unrelated projects like blinking xmas trees or garage door openers! So, what I would like to do is the following:

- use components of the MHP as small tutorial projects, ie start with the core, and make it do something very simple

- provide very clear explanations of *exactly* what is going on at a hardware level, ie so clear that a beginner with a decent book on electronics can learn the whole circuit

- provide a series of code for the 16F877 and 18F452 that uses the MHP and runs in   a graduated manner from the extremely simple ( say blinking an led directly off the core and/or DOUT module ) to broken out versions of the actual code used in MIOS, and eventually to an explanation of how MIOS actually does it.

- provide seperate tutorials for various parts of the platform so that one is not overwhelmed by the amount of material. ie a tutorial on how the AIN gets it's data, with nothing else going on

- eventually also provide tutorials on how to integrate MHP platform projects directly with various computer systems using drivers and frontends written in C/C++ using open source cross platform libraries and development tools such as GCC, portmidi, portaudio, etc. I personally will be doing all my work on Linux using PikDev and the GNU Pic tools, but I would like to make sure that all examples will work on Linix, Windoze, and Mac.

Now, I will need help, and of course Thorsten's blessing; I dearly hope he would like people to learn from his fantastic work. I myself  am a good technical writer and am happy to write the tutorial code, explanations, and comments. I will definitely need assistance from someone who knows a lot more about electronics and who can help explain the circuits and write tutorial material for that side of things. And of course testers for all platforms.

This is something I will be doing myself no matter the interest level as I just want to learn to make heavily customized computer music interfaces, but if there is interest from the rest of the community, then I will put the work in to make things accessible, understandable, and relevant to others. Please tell me what you think, and let me know if you'd like to help.

Thorsten, if you think this is a good idea, perhaps a new section for it in the forum would be a good starting point for brainstorming? At any rate, please let me know whether you like the idea and also any suggestions you have.

Thanks

iain

[Guest XORNOT]

Well, no one else has responded yet so I'll respond to myself! I''ve been looking closely at the schematics and I think this is really a feasible project. I would also like to document very clearly how MIOS works, which will be a lot harder. Anyone interested in this side of things, let me know. I'm thinking a comprehensive programmer's guide to MIOS.

iain

[arumblack]

I am about to start my digital electronics course at school (2 weeks!), and I had planned to break down everything about the MBHP modules for my own personal knowledge. I would be glad to give a report on theese things as I discover them for myself. This could take a little time, and surely there are people that already understand theese things fully, but as I will be doing it anyway, I thought I would offer.

[jimhenry]

I think improved documentation is one of the most frequent requests and something that almost everyone could benefit from. As I am sure you realize it will be a HUGE undertaking. I wrote a very modest explanation of how to make a cable for the LCD and it took far longer than actually making a cable. My suggestion would be to define some small finite documentation task that can be the cornerstone for your overall vision. The experience of doing that will probably give you a much better idea of how to tackle the balance of the project.

Have you looked at the WIKI documentation? Perhaps giving that some direction as an editor would leverage your contributions and be a way to encourage more contributions from the community. There really is a lot of documentation for the MIDI Box although possibly not everything you have in mind. It is just hard to find and not particularly coordinated. An editor who can organize what has already been done, rewrite as necessary for continuity, identify gaps, and locate a volunteer to write material to fill those gaps could probably accomplish quite a lot in a reasonable length of time.

[TK.]

Thorsten, if you think this is a good idea, perhaps a new section for it in the forum would be a good starting point for brainstorming? At any rate, please let me know whether you like the idea and also any suggestions you have.

the new section is now available: MIDIbox Documentation Project

Best Regards, Thorsten.

[Jidis]

Funny, I had read through Iain's other posts, and just found this one. We seem to both be looking for the exact same type of MIOS docs for the exact same reasons. Definitely the part about helping musician types get a hold on assembler and higher level languages through something they're interested in and can use. I took piano lessons years ago, while I was in-between studios and had no keyboard or sampler set up in a convenient location. With nothing but the boring theory material to work with and nothing fun to apply it to at the time, I rapidly forgot everything I learned.

I like the idea of a printable, standalone text or PDF document for this one element of the MIDIBoxes, maybe with a brief table of contents to organize it. Most of it doesn't seem like it would necessarily need pictures or a web page, and it would be a great thing to have outside the computer.

It's a shame the technical world and the writing world are so "separated", but I guess most of us would be better at describing "nerd things" to each other than your average writer ;D  (maybe we could recruit Craig Anderton or somebody)

                                                                     - George 

[pwx]

Hi!

Good idea!!!!! ;D

When I build my midiboxes, everytime I got the same Problem....

soldering the hardware, I´ve learned with this great projects..... but programming the PIC.... I don´t know where to start learning it.....

It would be great to have something with is the "connection" between both sides.... :)

pwx

[Jidis]

PWX-

As a fellow newbie, I would recommend the book I used, which was "Easy MicroControl'n" by Square One. It teaches you on the smaller PIC 16f84. With that and a bunch of other small MIDI PIC code files from the web, you should be able to get a feel for the basic concepts. I never found a good "next book", as the Square One book doesn't really get into a bunch of stuff (macros, for instance, or many of the features of the bigger PIC chips). I liked it a lot and had no trouble with it, but I more or less *hate* this Kernighan & Ritchie "C" book that I'm carrying now, and it seemed to be very well accepted as a beginner's reading.

                                                                     Good Luck!