BeagleLibs Weekly Report Thread

This is where I will be posting my weekly updates for the BeagleLibs project.

This week the goal was to set up the git repositories, write up and API overview document, get an introductory video up and get GPIOs implemented.

I’ve completed setting up the github repository for the Rust portion of the project, which can be found here
I also added continuous integration (CI) to the project in the form of TravisCI, which will help ensure that the library works properly.

I’ve done a lot of brainstorming about the API but have yet to transfer that to a concrete document that will be posted online.
I hope to get it done by the end of this week.
My mentor has helped me a lot by providing links to other projects with similar goals, which helps me decide what the right way forward is for BeagleLibs.

I completed the introductory video last week, which can be found on the eLinux Wiki.

I’ve been implementing the GPIO code and have a decently working version on my local check out which I hope to polish and push very soon.
The one thing that has been hanging me up is deciding how I want error handling to work, but I think I have a decent solution worked out.

Overall it’s been a decently productive week, though I feel I’ve had a bit of a slow start.

Oops, forgot to include the link to the repository: https://github.com/ekmecic/bb_rust

This week I finished up and published the implementation of the GPIOs and got a working prototype of PWM functionality that I need to test further before publishing.
Didn’t complete as much of the documentation for GPIOs as I would have liked (eg. comments in the implementation), but I did write some example programs that demonstrate the functionality nicely and are documented.

Tasks for next week include making up for the lack of documentation, adding the library to crates.io, and completing the ADC implementation.
I also have some code already written for the ADC which should speed up the development process and get me back on schedule.

One of the things I’m really happy with as part of the GPIO and upcoming PWM code is the error handling.
Other libraries I’ve used make it a pain to figure out the where/why of your program crash. If you make an error with bb_rust a nice error message is printed out telling you exactly where and why the error occured (eg. “Failed to export pin #45”) along with a full backtrace.
This makes debugging your code a lot easier compared to printf or wolf fence debugging :slight_smile:

Lots of news this week for BeagleLibs!
The GPIO, PWM, and ADC modules were all implemented, documented, tested, and published, along with example programs for each module.
The library was also renamed from bb_rust to libbeaglebone, whose source can be found at the github link below.

Furthermore, libbeaglebone was uploaded to crates.io, which makes it publicly available and easy to access for anyone with a Rust installation!
With the inclusion of libbeaglebone on crates.io, automatically generated documentation is now available on docs.rs (a link can be found below).

Overall, things are back on schedule and looking good.
The target for next week is implementing the UART module which is a challenge I’m looking forward to :slight_smile:
I also plan on soliciting some code reviews from members of the Rust community along with some feedback from members of the BeagleBoard community.

Links
New Github link: https://github.com/ekmecic/libbeaglebone/
crates.io: https://crates.io/crates/libbeaglebone
docs.rs: https://docs.rs/libbeaglebone/libbeaglebone/

This was a slow week, mostly worked on getting UART done and improving the existing documentation.
The UART implementation is simple since it’s all layered over the kernel interface.
There’s some tricky bits relating to the termios API but I think I’ve got them ironed out.
I’ve got a mostly-working version locally, just need to clean it up and finish up testing before publishing it.

In terms of documentation improvements I added more detail as to why the library handles errors, as well as generally improving the examples and comments to make it easier to get into.
I didn’t get a chance to ask for a public review of the library yet, so I plan on doing it this week once I push the UART code.

The plan was to have UART, I2C, and SPI done this week but I will be late in finishing them.
I’ve got an implementation of UART (after several rewrites) but I’m not yet happy with the code as it stands.
Currently, it’s a wrapper of an existing library and there’s a lot of code duplication that I don’t like.
I’m still working on a better way to write that.

In the meantime I’ve been working on the I2C implementation, which is proceeding at a decent pace.
I’ve got some functionality done, but it requires testing.
Some syscall code (ioctl, etc) is also a pain in Rust due to the strict safety requirements, which has slowed me down.

In the mean time I’ve identified a list of improvements/TODOs for the library before final release.
These include implementation details like avoiding excessive file opens/creates for the mutator methods, using more meaningful error types etc., and others are user-facing, like better constructors, following Rust design patterns more closely, and improvements to documentation.
I’ve completed a few of these TODOs and have them waiting in staging and plan on implementing the rest once the library is feature complete.

Most of the problems I’m currently facing are due to a lack of time.
Conservatively, I’d say it’ll be a week and a half before all the things I’ve talked about in this post are complete.
This isn’t a cause for concern for the project as a whole, since the first few milestones for the Go project will be easy to complete after doing them in Rust.
Overall I’m not as far along as I’d like to be, but things are moving forward.

UART and I2C completed and uploaded, although I’ve left most of the documentation and examples out in preparation for a rewrite of most of the library’s documentation.
The only thing left in the Rust side of the project is to get the SPI completed and then to get of the TODOs I mentioned in the last report done.
Work has begun to this end and I hope to complete it next week.
After that I’ll work on the Go library, which I believe will proceed much faster since the Rust library will have been completed.

This week I’ve cleaned up the I2C and UART modules I completed last week with additional documentation and some refactoring.
I’ve also gone over the rest of the documentation of the library and cleaned it up and refactored it.
Most significantly, I’ve added module documentation that helps users get familiar with the BeagleBone with examples on how to configure it before use, important information (input limits etc) and so on.
I’ve found this kind of material lacking in my own use of other libraries so I think it’s a very important addition to help people get up and running quickly.

I haven’t yet pushed the last 2 things needed to complete the library: the SPI driver and the other fixes/refactors I’ve been working on, but I’m confident I’ll be able to do it by Friday.
I’ve also been setting up my development enviroment for the next task ahead of me: the Go library.
By the next report I should be done the Rust library and have the Go library started.

This week finally heralds the feature completeness of the Rust libbeaglebone!
SPI has finally been implemented and should be ready for preliminary use.
I’ve borrowed a lot from the rust-embedded libraries as part of the SPI and I2C implementation, and so I’ve also contributed back a PR with some of my changes and other fixes/updates to the code.
I also plan on sending some more PRs in as I find the time to work on their code.

Like I mentioned in the last update, work has begun on the Go library but I wasn’t able to publish it yet due to tight timing.
GPIO should be up as soon as tonight, and as late as the end of the week.
PWM should follow soon after, and I anticipate I’ll be back on track soon.
Overall things are looking good and progress is being made towards the end goal, which is on track and on schedule.

I apologize for my absence at last week’s meeting and missing the weekly report.
I currently have final exams which are proving to be very time consuming and I was unable to attend the meeting as my final was at the same time.
Unfortunately I’ll also miss this week’s meeting as I have a simultaneous final, however it is my last final exam so I will be there for all remaining meetings :slight_smile:

This week brings new progress in the Go library, with ADC and PWM being completed leaving just I2C, SPI, and UART on the todo list.
I’ve found Go to be an interesting companion to Rust and a breath of fresh air.
There’s several things that are quite nice compared to Rust, like the much faster compile times and simpler syntax, but there’s also a couple of things that are a step down.
For example, the documentation tooling for Rust is in a league of its own which is critical for a project like BeagleLibs which aims to be accessible to beginners.
Go has godoc, but it isn’t as easy to work with or featureful as rustdoc, especially when it comes to providing examples.
Furthermore, the error handling situation also left me wishing for the error-chain library, which makes it easy to give nice backtraces and error messages when something goes wrong.

Overall though it’s been a pleasant experience and I’ll keep an open mind going forward.
Things are moving along nicely and I anticipate the completion of I2C next week.

This week has been quite hectic with my travel schedule, but I managed to get the I2C implementation complete.
The work done was helped along by having the Rust code to go off on, but I also borrowed Dave Cheney’s ioctl wrapper function which cut down on the boilerplate required for ioctl syscalls.
The approach I took for this I2C implementation differs from the Rust one and is considerably simpler.
In Go I used the i2cdev sysfs interface to do the r/w from I2C, whereas in Rust I used only the ioctl interface.
This has the benefit of better performance since you’re not dealing with file I/O, but it has the downside of a lot more boilerplate code.
Since the point of this library is simplicity and ease-of-use rather than raw performance, I’m debating rewriting the Rust code to follow the same approach.
If I do, it’ll be done the end of the week.

Now that exams are done I have a lot more time to work on the project so I anticipate that I’ll be able to complete UART handily by the next deadline and get working on SPI.
After that the goal will be to polish the work to completion :slight_smile:

Part of this week’s brought us back to the Rust library, where I refactored the I2C implementation to make it simpler and safer.
The changes made it similar to the Go implementation, which has the i2cdev subsystem do the bulk of the work instead of ioctls.
ioctls are quite a pain to work with in Rust and lead to some pretty ugly code IMO.

I also implemented the pin aliasing for GPIOs, PWMs, and ADCs, which was a pleasure in Rust due to the nice type system.
The implementation is basically just a huge enum that aliases a “nice” pin name to either an integer or a tuple in the case of PWM.
For example:

enum Pins { GPIO_P8_42 = 75, PWM_P9_22 = (0, 0), AIN_2 = 2, }

This makes referring to pins much easier especially with PWMs.
Instead of doing something like:

`
let mut led = PWM::new(0, 0); // which PWM does this refer to?!

`

you will be able to do:

`
let mut led = PWM::new(PWM_P9_22); // much better

`

In effect, you can just look up the name of the pin you want on some pinout image and use that instead of having to hunt around for information in data sheets etc.
I haven’t worked on the Go implementation yet, but I feel like it won’t be as nice especially since Go doesn’t even have enums.

I have been working on the UART and SPI implementations for Go, though I have not completed them yet.
All of the changes (I2C, pins) I’ve mentioned so far are still sitting in my staging area, and I’ll push them when I’ve done a little more testing on them.
Once they’re tested and pushed, the priority will shift to UART and SPI which will bring us to the conclusion of the project.
This is cutting it closer than I would have liked, but I’m still confident I’ll get it done.