Using Swagger APIs with Unity

Swagger lets you define API structure in a machine-readable way. This enables all kinds of cool functionality: automatic docs, code generation across languages, etc. Here’s the workflow I’ve been able to sort out for consuming Swagger APIs in Unity. (Note: I’ve tested this on a Mac, but haven’t tried it on a PC yet.)

  1. Load your Swagger specification into the editor at http://editor.swagger.io. (The easiest way is just to copy and paste it into the editor window.)
  2. Verify that the auto-generated documentation on the right looks correct.
  3. Choose “CsharpDotNet2” from the “Generate Client” dropdown.
  4. Unzip the downloaded CsharpDotNet2-client-generated.zip file.
  5. Open a terminal window.
  6. Go to the vendor directory of the new unzipped download. (e.g. “cd ~/Downloads/CsharpDotNet2-client/vendor/”)
  7. Download the required JSON library by typing this in the command line: nuget install Newtonsoft.Json -version 7.0.1
  8. Download the required REST library: nuget install RestSharp.Net2 -version 1.1.11
  9. Move back to the root of the downloaded folder. cd .. or cd ~/Downloads/CsharpDotNet2-client/.
  10. Build your DLL: ./compile-mono.sh. You’ll get a warning about not being able to open nuget.exe. This is fine.
  11. Your DLL is now in the “build” subdirectory of the downloaded folder and is called “IO.Swagger.dll”. Copy this to your “Scripts” folder in Unity.
  12. Find “Newtonsoft.Json.dll” (vendor/Newtonsoft.Json.7.0..1/lib/net20/Newtonsoft.Json.dll) and copy it to your “Scripts” folder in Unity.
  13. Find “RestSharp.Net2.dll” (vendor/RestSharp.Net2.1.1.11/lib/net20/RestSharp.Net2.dll) and copy it to your “Scripts” folder in Unity.
  14. Unity loads the DLL and makes the IO.Swagger namespace available to you.

Using it:

Take a look in the docs folder of the project you downloaded from the Swagger editor. It includes nice Markup files with C# sample code documenting the APIs in your new DLL. The sample code makes a great starting point for accessing the DLL’s functionality.

Big Frustrating Caveat:

The RestSharp library defines “System.Action” and “System.Func” as does the .NET runtime. Unfortunately, this means that if you have code in your project that relies on either of these (like Google’s Daydream library), you won’t be able to get it to compile. In theory, you should be able to work around this by setting up Unity to use external references and referencing those that way, but I’ve been unable to get that to work. As far as I can tell at this point, the best way forward in this case is simply to write your own client code using RestSharp Unity or another library designed for creating REST clients. If someone has a better working approach, I’d love to know about it.

Moving to VR

About a year ago, I decided it was time for a career shift. I managed a fabulous team of mobile developers who were a joy to work with, but I missed creating things. I talked to my boss at Mutual Mobile about the problem; he encouraged me to chart out a way back to an engineer role within the company.

I thought carefully about my options. I could go back to iOS engineering, which my previous boss had done. He was delighted with the change and had no regrets whatever about stepping down from management to an engineering job. But I enjoy learning and figuring out new things and, while iOS is a fantastically enjoyable platform to develop for, iOS 10 seemed pretty mature. I moved from web development to mobile because the web stopped feeling like the wild west. Now I had the same sense about mobile.

So I looked at alternatives. Mutual Mobile had a months-old Virtual Reality practice at that point that was gaining steam. While I hadn’t yet spent any serious time with Unity, which the team uses for its work, my son and some of my fellow engineers both had and were clearly enjoying the experience.

I floated my plan to retool myself into a VR engineer to my boss and the VR team, all of whom were gracious enough to give it an enthusiastic thumbs-up. So in early 2017, I began a self-administered crash course in Unity and VR. I found Unity’s online training materials to be excellent, and by the time we executed my official transition to the VR team, I was able to jump in and contribute to the team without a problem.

(I was still green compared to the other two excellent engineers working on our projects, but made up for it by continuing to do management of our engineering and project management teams.)

I’ve now gotten to contribute to a Cardboard project and do all the engineering for an Oculus Rift project. (The former should be available in the mobile app stores soon, and the latter will be installed in the Bass Pro HQ in Springfield in a few weeks.) The team’s also doing work with several other really interesting clients; I’m excited about the work ahead.

Now that I’m past the initial hurdles in Unity, I’m learning things I think might benefit other developers and/or VR enthusiasts. Accordingly, I’m going to post things here to document my learning. My areas of particular interest include: Good Software Architecture in Unity, Cool Stuff our Team is Doing, Using Physical Props in VR, and Accessibility in VR.

If you’re interested in any of these areas or just in creating VR, please get in touch or just follow along. I’m excited about this next phase of my career, and will be happy to have company!

A Few Articles from Mutual Mobile

Over the past year, I’ve written a few articles for Mutual Mobile that I’ve never gotten around to posting here. They’re all more or less technical, so may not be interesting if you visit for personal and family stories. If you’d like to see any of these, they’re linked here.

Accessibility: What It Is, Why It Matters, and How to Do It

I did a presentation at CocoaConf Dallas today on how, as a developer, to make your iOS apps usable by people with visual impairments. It was a lot of fun, and seemed to be well-received by the conference attendees. If you’d like to see the slides, you can download them here:

Download Accessibility Presentation

In addition, I announced an open source component I wrote to make accessibility testing easier for developers. It’s called SMAccessibilityOverlay. By adding it to an app under development, you can temporarily display an overlay that quickly shows what areas of the screen have been marked as accessible, and what labels are associated with those regions:

Accessibility Overlay Screenshot

If you’d like to try it out in your app, you can download it from GitHub here. I’d also be delighted to have input on it, either in the form of suggestions (good) or code contributions (better) or encouraging beer purchases (best).

Pebble First Impressions

I was a fairly early backer of the much-publicized Pebble smart watch. After being wristwatch-free for years, I’ve been wearing mine for nearly a week now, and have some early first impressions I thought I’d share for the curious.

First off: it’s a good-looking timepiece. While the 144×168 screen resolution sounds almost absurdly low for those of us who have been spoiled by full-color retina displays, it look just fine in context. The high-contrast display technology is great, and is visible in a wide range of conditions. Being able to turn on the backlight with a quick wrist-flick is terrific, though it does make playing hide-and-seek in the dark more challenging (as my kids will attest).

The on-device software is solid and well thought-out, with a clear, usable interface a bit reminiscent of the original iPod. Scroll views show a shadow at the top or bottom if there’s more content to display. Controlling music works like a charm with the built-in music app or any others that use Apple’s media control APIs. (Combined with Pandora and Apple TV, I can control music streaming from the Internet through my home sound system from my wrist. It’s the future!)

The included watch faces are fairly varied and interesting, with the binary display being a favorite of mine, though it takes me 10 seconds to figure out the time when someone asks me. And thanks to the support for notifications, I’ve known what those incessant chirrups coming from my phone are about without having to fish it out of my pocket.

Funnily enough, my biggest beefs with the out-of-the-box experience have to do with iOS. Pebble is taking advantage of some newer features in iOS 6 that haven’t been widely used yet, and there are still some rough edges on Apple’s side of things. Notifications have to be reset whenever the Pebble and phone lose contact with each other (which includes restarting either device, using Airplane mode, rebooting your phone for a system update, etc). Additionally, when the watch talks to the phone and the Pebble app isn’t already running in the background, iOS throws up an obtrusive alert telling you that the watch is trying to talk to the phone. It then launches the Pebble app into the foreground if you give it the permission to communicate it’s asking for.

There are, however, a few knocks I can level at the Pebble itself. If one gets multiple notifications in rapid succession — for example, when the mail app finds a few new messages in your inbox — the first notification immediately gives way to the latter, with no way to rewind and see the initial information.

The battery life doesn’t seem near as long as the advertised week. I admittedly haven’t run it into the ground yet, and I’m not 100% sure I gave it a full charge, since there’s no indication of charge status when it’s plugged in*, but so far it seems to last closer to 4 days than the week the company cites. (Oops — it just expired. Looks like the 4 day figure’s about right, and the low battery warning seems to appear 12-18 hours before it gives up the ghost.)

The most egregious problem, however, is the SDK. Or more precisely, the gaping hole where it should be. As detailed on http://www.ispebblesdkshipping.com/ (a spoof of Pebble’s own http://www.ispebbleshipping.com/), the kit that would allow developers to create new apps and watch faces for the Pebble was promised first for August 2012, then by January 23, then when the watch shipped. As of today, it still hasn’t turned up, and the company has been tight-lipped about what is causing the delay.

Given that the hardware specs have actually been improved since the Kickstarter finished, my hope is that the programmers are simply hoping to deliver something higher-quality and more capable than they’d initially planned on. The lack of communication, however, is a bit worrisome since many folks who have bought one of the devices did so out of a desire to be able to develop for it.

But overall, I’m happy with this first version of the Pebble. The existing functionality seems solid, and the possibilities for future improvements will be exciting once the SDK is finally out. If the company has to choose between putting something out soon that’s half-baked, or taking longer to create something they’re really proud of, it’s clear they choose the latter — a decision I applaud.

But now I have to go charge my watch.

* UPDATE: There actually is an indicator that lets you know when the watch is fully charged, but until the Pebble folks graciously pointed out the help page, I hadn’t been able to sort out the iconography they are using.

Why is Programming Fun?

One of the best explanations I’ve ever seen of the appeal of what I currently get to do as a profession.

Why is programming fun? What delights may its practitioner expect as his reward?

First is the sheer joy of making things. As the child delights in his mud pie, so the adult enjoys building things, especially things of his own design. I think this delight must be an image of God’s delight in making things, a delight shown in the distinctness and newness of each leaf and each snowflake.

Second is the pleasure of making things that are useful to other people. Deep within, we want others to use our work and to find it helpful. In this respect the programming system is not essentially different from the child’s first clay pencil holder “for Daddy’s office.”

Third is the fascination of fashioning complex puzzle-like objects of interlocking moving parts and watching them work in subtle cycles, playing out the consequences of principles built in from the beginning. The programmed computer has all the fascination of the pinball machine or the jukebox mechanism, carried to the ultimate.

Fourth is the joy of always learning, which springs from the nonrepeating nature of the task. In one way or another the problem is ever new, and its solver learns something: sometimes practical, sometimes theoretical, and sometimes both.

Finally, there is the delight of working in such a tractable medium. The programmer, like the poet, works only slightly removed from pure thought-stuff. He builds his castles in the air, from air, creating by exertion of the imagination. Few media of creation are so flexible, so easy to polish and rework, so readily capable of realizing grand conceptual structures. (As we shall see later, this very tractability has its own problems.)

Yet the program construct, unlike the poet’s words, is real in the sense that it moves and works, producing visible outputs separate from the construct itself. It prints results, draws pictures, produces sounds, moves arms. The magic of myth and legend has come true in our time. One types the correct incantation on a keyboard, and a display screen comes to life, showing things that never were nor could be.

Programming then is fun because it gratifies creative longings built deep within us and delights sensibilities we have in common with all men.

From The Mythical Man-Month, by Frederick P. Brooks, via Federico Grilli

Back in My Day…

…we didn’t have fancy 3D graphics! We had half-acre pixels and 8 colors and we liked it!

Today while visiting garage sales with my lovely bride, I stumbled across an October 1982 National Geographic with these ads for game consoles of the day. I was 12 when these ads were run, and remember fondly many hours whiled away with friends playing both Atari and Intellivision. (I never did much with the Odyssey², probably because I saw these ads and the “wizard” gave me nightmares.)

Intellivision Ad

In 1982, these screenshots actually looked different from each other.

Odyssey Ad

The Wizard has a Power Supply stuck to his fingers. Also, his legal department apparently lacked the acumen to get a proper "Wizard of Wor" license.

Odyssey Speech Synthesizer Ad

If the first word you typed upon getting the speech synthesizer module for the Odyssey² was "Geewizbang", it's a pretty good bet you had no friends.

Going Mobile

On January 2, I”ll be going to work for Mutual Mobile, an Austin-based company that specializes in application development for iOS, Android and Blackberry devices.

“But Sean!” I hear you, Rhetorically Convenient Reader, cry. “You just started working for Magnolia back in March! Why are you moving on again so soon?” That’s a good question. It doesn’t have anything to do with Magnolia: it’s a terrific company, filled with great people that I am glad to call coworkers and friends. That fact made this decision especially hard, as I knew I’d be seeing less of these people I quite like (and would, honestly, be making their lives tougher in the short term with my departure).

But as much as I like Magnolia, the nature of their business means that my work there revolved around two things: Java and Sales. Java is an industry standard for creating software of various stripes, but it’s a very buttoned-down, staid environment to work in. It lacks the creative energy and — is it silly to say this? — joy that I see in the communities that exist around some of the more dynamic, less-widely used languages like Ruby and Python and Lisp (for you AI wonks out there). I can get work done in it just fine, but the number of times a spontaneous “Awesome!” escapes my lips while doing so is vanishingly small.

The other focus of my last 9 months has been selling Magnolia to various companies. I think the software is a phenomenal piece of work, and really well-suited to a whole variety of Web Content Management scenarios. But while I can do an effective job helping to demonstrate and sell it, there’s no frisson associated with doing so for me.

I like technology for what it can do for people. I like creating it because doing so is much like fashioning a beautiful, intricate bit of clockwork, or a complex bit of musical counterpoint. There is immense satisfaction in creating something that works elegantly and beautifully. Unfortunately, telling people about how terrific other people’s work is provides very little of the satisfaction that actually doing that creative work oneself. If I’m going to be in the technology world, I want to make cool stuff for normal people, not to sell cool technology to corporations.

So, Mutual Mobile. I’ll be starting there as an iOS Manager, which means that not only will I be getting to work directly on creating some great stuff for their impressive list of clients, but I’ll also be getting to help figure out the best way to help the other developers there do their best work as well. I’ll be hanging around a bunch of really smart folks, and will doubtless be learning tons about iPhone development and other mobile disciplines. The company seems like a marvelous place to hang one’s professional hat — a vibrant company culture, entirely self-funded with no investor money involved, just named by Forbes as one of America’s most promising companies, and has its company meetings at the Alamo Drafthouse, one of my favorite places in Austin. And the downside of facing a commute again is largely ameliorated by the fact that Texas State University runs a shuttle bus from San Marcos with wireless Internet to a park 4 blocks away from the office. Sweet!

I’m excited about this next adventure, and will be posting more about it once I’ve got my feet under me. Wish me luck!