Arduinos In Space: Arduino library for OiS controllers

[stibbons]

I’ve been putting off designing hardware until I’ve logged a fair bit more time in game. But that doesn’t mean I can’t work on the code for it, right?

Arduinos In Space is a library to encapsulate the OiS serial protocol and provide what I hope is a friendly, easy to use interface while still being fairly fast. As an example, here’s one of the included demo sketches for a controller with a comically large main engine control button:

#include <Bounce2.h>
#include <ArduinosInSpace.h>

const int engineButtonPin = 2;
Bounce engineButton = Bounce();

ObjectsInSpace OIS(Serial, 0);

void setup() {
  // Set up Bounce for button debouncing
  pinMode(engineButtonPin, INPUT);
  engineButton.attach(engineButtonPin);
  engineButton.attach(engineButtonPin);
  engineButton.interval(5);

  // Open the serial connection and perform handshaking
  Serial.begin(9600);
  OIS.begin();

  // Synchronise with the game, registering commands we want to send
  OIS.registerCommand(BURN_MAIN_ENGINE);
  OIS.registerCommand(STOP_MAIN_ENGINE);

  // Complete synchronisation and activate the link
  OIS.activate();
}

void loop() {
  // Update button state
  engineButton.update();
  if (engineButton.rose()) {
    // Button has been pressed, so burn engine
    OIS.sendCommand(BURN_MAIN_ENGINE);
  } else if (engineButton.fell()) {
    // Button has been released, so top burning
    OIS.sendCommand(STOP_MAIN_ENGINE);
  }
  OIS.update();
}

All known request and command types are supported. Included are a handful of example sketches showing how the commands, and callbacks for data requests work. It’s still a work in progress, with a few rough edges. But all the functionality I was aiming for is there.

If you’re interested, check it out here:
https://bitbucket.org/pjhardy/arduinosinspace

[Nocturnal]

Looks good. A generic callback within the library to handle simple buttons and leds might be a good addition, especially since it’s likely to be the major use case. I’m assuming with the callbacks, channel is the unique number assigned to each request type. So one callback function can handle multiple requests. Something small that seems to be missing, instructions on downloading and “installing” the library for people not familiar with the process. I didn’t look to closely, so I might have missed that.

I look forward to trying it out with this.

[stibbons]

Just pushed a 0.2 release. This changes how callbacks are handled - the library now takes care of converting data from the game. I think I’ll be adding “raw” callbacks back in, to get similar behaviour to previous versions. But removing the need to manage data types like that was one of my goals.

At this point, barring any major problems, the only real work left to do is flesh out the API docs and write some more examples. Should be ready for a general release after that.

[stibbons]

A generic callback within the library to handle simple buttons and leds might be a good addition, especially since it’s likely to be the major use case.

I’ll have a think about a general way to do this that covers most use cases. But to be honest it’s not a major priority.

I’m assuming with the callbacks, channel is the unique number assigned to each request type. So one callback function can handle multiple requests.

Yep, that was the intention. Right now the register functions return a boolean for success/failure. But changing that to return the ID instead sounds worthwhile. There’s no real elegant way to get the IDs otherwise, except knowing that they’re deterministic and increment in the order they’re added.

Something small that seems to be missing, instructions on downloading and “installing” the library for people not familiar with the process. I didn’t look to closely, so I might have missed that.

That was slightly deliberate. Once I’ve got a stable release it’ll be installable via the Arduino library manager, and I have a strong preference for automatic installation. Until then, I’d suggest grabbing the zip file from the repository downloads page, and install it following the Arduino library docs. Will add that to OP.

[stibbons]

And because hacking code on the train is fun and exciting, I’ve finished a 0.3 release. From the changelog:

• Added registerBoolRaw(), registerIntRaw(), registerFloatRaw() to handle data requests with a “raw” callback - this callback receives the int from the game directly with no postprocessing.
• All register functions now return an int instead of a boolean. This int represents the channel ID of the request - it correlates to the channel int passed to callbacks. A return value of -1 indicates failure - the channel was not registered. This is a breaking change.
• Refactoring of the registration code. Even with the other changes existing example sketches clock in at a handful of bytes smaller.

[stibbons]

Move fast, hopefully don’t break anything major. I’ve pushed a 0.4 release to bitbucket. The changelog:

• Added some debug code with an error callback. #define OIS_DEBUG, then add a callback using the errorHandler() method, and the callback will be called when errors are caught. Currently only alerts when the serial receive buffer is full.
• Shuffled some code around for tidyness.

The library is as feature complete as I can think of. My basic tests work, will hopefully find some time to build out a larger demo with a number of different inputs and outputs before OiS goes early access, to make sure nothing goes haywire at scale. But at the very least I plan to have more complete docs than the README, as well as a real, slightly easier to install release.

[Segwegler]

Do you mind if I add this to the wiki?
https://oiswiki.sysadninjas.net/wiki/Arduino_Librarys