c.cc

occam-pi Documentation

occam-pi is not the newest language on the block, but it is part of a small family of languages that are inherently parallel. Erlang, Google’s Go, and XC by XMOS are three of the few languages that were designed from the ground up for expressing code that is intended to run in parallel. (And yes, there are others. But they’re not common. Well, there’s CUDA… but that’s not a simple tool to dive into, and it doesn’t work on your $20 Arduino.)

We’re using occam-pi because the language is:

• Small. It has very little syntax, and a small grammar.
• Parallel. It has the keyword PAR, which makes things run in “at the same time.”
• Free and open. The tools are all freely available, and open.
• Portable. It runs on everything clusters and servers to embedded systems like your Arduino.

Plumbing for the Arduino

We wrote Plumbing for the Arduino to help get you started. It is, admittedly, in need of expansion. However, it is a good start if you’re new to occam and want to work with the Arduino.

UPDATE 20150610: And, it reflects a completely different IDE. Plumb makes some things much easier… so, it needs updating for several reasons.

Resources: occamdoc

If you want to use the Plumbing libraries on the Arduino, you may find this documentation to be useful. We call it “occamdoc,” and it is directly generated from the code for the library itself.

Resources: Books

In some ways, there are a wealth of resources for you to use. In other ways, you’re going to wish you had better documentation. Because you’re working with a free and open project, we want to encourage you to either (1) document and report things that you wish were better, or (2) contribute fixes/documentation/solutions back to the project. That’s how real open source software works, folks.

There are a number of books. These are out of print, and scans of them are made available to you here:

• A Tutorial Introduction to Concurrent Programming in Occam by Dick Pountain and David May.
• Programming in occam2 by Alan Burns.
• Introduction to the Programming Language Occam by Daniel Hyde.
• An Introduction to occam2 Programming by Bowler, Kenway, Pawley, and Roweth.
• Introduction to occam2 on the Transputer by Brookes and Stewart.

It is important to note two things as you use these resources. First, occam-pi is a superset of occam2. Therefore, most anything you read about occam2 will be true for occam-pi. Also, if you are working with an Arduino, then you are (for all intents and purposes) working with the occam2 subset of the language. In other words, the above books can be viewed as guides to the language we use on embedded platforms like the Arduino.

One of Matt’s favorites in this set is the “Tutorial Introduction” by Pountain. Dick is still writing and thinking about these issues (see his thoughts on “PriPar machines”). And, if you’re keen, David May is still working on these issues in hardware; the company XMOS is producing parallel processors today that are clearly inspired by the Transputer and the occam programming language. Someday, we hope to provide a compiler that targets these processors.

Join the Community

You may find (some) resources at concurrency.cc of use. I say “may” and “some” because there’s only so much we can do to help with static text.

REALLY, you should join the user’s mailing list. Why? Because when you have questions about occam-pi, we would like you ask those questions there. As developers exploring the use of occam-pi on the Arduino, you’re going to be asking questions that may benefit other members of the community. Or, there may be many members of the community who are able to answer your questions. Therefore, it is up to you to ask those questions in a forum where your answers will not only benefit you, but others as well.

Resources: On the WWW

There are fewer resources on the WWW than I would like, but you may find them useful just the same.

• The occamdoc for the Arduino modules may be very useful. (See note, below…)
• On occam-pi.org we have some links to a variety of learning resources.
• The occam-pi reference guide is a good quick reference.
• The occam 2.1 reference is a longer document, but covers details of the language that you may be curious about.
• Dr. Fred Barnes is a driving force in the development of occam-pi, and his website has many useful resources.

Also, we can modify/improve the Plumbing module as a result of your use. That is, I have commit rights on the repository, and I write a lot of the documentation… so, if you think we can improve the Plumbing module, by all means… make suggestions on the users list, and we can discuss them and (most likely) put your suggestions into practice.

Giving Back, Making Contributions

If you’d like to help improve anything we’ve produced — our software, our hardware, our book, or our website — please join the developers mailing list and talk to us there.

If you’re familiar with Subversion, we do make repository space available for members of the community. This means your code is backed up, others can see what you’re working on (and help!), and your efforts benefit many, even if you’re just getting started. (It also makes it easier for others to help you out.) Note, though: your code must be released under a GPL- or LGPL-compatible license if we’re going to host it.