An I/O controller for virtual pinball machines: accelerometer nudge sensing, analog plunger input, button input encoding, LedWiz compatible output controls, and more.

Dependencies:   mbed FastIO FastPWM USBDevice

Fork of Pinscape_Controller by Mike R


This is Version 2 of the Pinscape Controller, an I/O controller for virtual pinball machines. (You can find the old version 1 software here.) Pinscape is software for the KL25Z that turns the board into a full-featured I/O controller for virtual pinball, with support for accelerometer-based nudging, a real plunger, button inputs, and feedback device control.

In case you haven't heard of the concept before, a "virtual pinball machine" is basically a video pinball simulator that's built into a real pinball machine body. A TV monitor goes in place of the pinball playfield, and a second TV goes in the backbox to serve as the "backglass" display. A third smaller monitor can serve as the "DMD" (the Dot Matrix Display used for scoring on newer machines), or you can even install a real pinball plasma DMD. A computer is hidden inside the cabinet, running pinball emulation software that displays a life-sized playfield on the main TV. The cabinet has all of the usual buttons, too, so it not only looks like the real thing, but plays like it too. That's a picture of my own machine to the right. On the outside, it's built exactly like a real arcade pinball machine, with the same overall dimensions and all of the standard pinball cabinet hardware.

A few small companies build and sell complete, finished virtual pinball machines, but I think it's more fun as a DIY project. If you have some basic wood-working skills and know your way around PCs, you can build one from scratch. The computer part is just an ordinary Windows PC, and all of the pinball emulation can be built out of free, open-source software. In that spirit, the Pinscape Controller is an open-source software/hardware project that offers a no-compromises, all-in-one control center for all of the unique input/output needs of a virtual pinball cabinet. If you've been thinking about building one of these, but you're not sure how to connect a plunger, flipper buttons, lights, nudge sensor, and whatever else you can think of, this project might be just what you're looking for.

You can find much more information about DIY Pin Cab building in general in the Virtual Cabinet Forum on Also visit my Pinscape Resources page for more about this project and other virtual pinball projects I'm working on.


  • Pinscape Release Builds: This page has download links for all of the Pinscape software. To get started, install and run the Pinscape Config Tool on your Windows computer. It will lead you through the steps for installing the Pinscape firmware on the KL25Z.
  • Config Tool Source Code. The complete C# source code for the config tool. You don't need this to run the tool, but it's available if you want to customize anything or see how it works inside.


The new Version 2 Build Guide is now complete! This new version aims to be a complete guide to building a virtual pinball machine, including not only the Pinscape elements but all of the basics, from sourcing parts to building all of the hardware.

You can also refer to the original Hardware Build Guide (PDF), but that's out of date now, since it refers to the old version 1 software, which was rather different (especially when it comes to configuration).

System Requirements

The new config tool requires a fairly up-to-date Microsoft .NET installation. If you use Windows Update to keep your system current, you should be fine. A modern version of Internet Explorer (IE) is required, even if you don't use it as your main browser, because the config tool uses some system components that Microsoft packages into the IE install set. I test with IE11, so that's known to work. IE8 doesn't work. IE9 and 10 are unknown at this point.

The Windows requirements are only for the config tool. The firmware doesn't care about anything on the Windows side, so if you can make do without the config tool, you can use almost any Windows setup.

Main Features

Plunger: The Pinscape Controller started out as a "mechanical plunger" controller: a device for attaching a real pinball plunger to the video game software so that you could launch the ball the natural way. This is still, of course, a central feature of the project. The software supports several types of sensors: a high-resolution optical sensor (which works by essentially taking pictures of the plunger as it moves); a slide potentionmeter (which determines the position via the changing electrical resistance in the pot); a quadrature sensor (which counts bars printed on a special guide rail that it moves along); and an IR distance sensor (which determines the position by sending pulses of light at the plunger and measuring the round-trip travel time). The Build Guide explains how to set up each type of sensor.

Nudging: The KL25Z (the little microcontroller that the software runs on) has a built-in accelerometer. The Pinscape software uses it to sense when you nudge the cabinet, and feeds the acceleration data to the pinball software on the PC. This turns physical nudges into virtual English on the ball. The accelerometer is quite sensitive and accurate, so we can measure the difference between little bumps and hard shoves, and everything in between. The result is natural and immersive.

Buttons: You can wire real pinball buttons to the KL25Z, and the software will translate the buttons into PC input. You have the option to map each button to a keyboard key or joystick button. You can wire up your flipper buttons, Magna Save buttons, Start button, coin slots, operator buttons, and whatever else you need.

Feedback devices: You can also attach "feedback devices" to the KL25Z. Feedback devices are things that create tactile, sound, and lighting effects in sync with the game action. The most popular PC pinball emulators know how to address a wide variety of these devices, and know how to match them to on-screen action in each virtual table. You just need an I/O controller that translates commands from the PC into electrical signals that turn the devices on and off. The Pinscape Controller can do that for you.

Expansion Boards

There are two main ways to run the Pinscape Controller: standalone, or using the "expansion boards".

In the basic standalone setup, you just need the KL25Z, plus whatever buttons, sensors, and feedback devices you want to attach to it. This mode lets you take advantage of everything the software can do, but for some features, you'll have to build some ad hoc external circuitry to interface external devices with the KL25Z. The Build Guide has detailed plans for exactly what you need to build.

The other option is the Pinscape Expansion Boards. The expansion boards are a companion project, which is also totally free and open-source, that provides Printed Circuit Board (PCB) layouts that are designed specifically to work with the Pinscape software. The PCB designs are in the widely used EAGLE format, which many PCB manufacturers can turn directly into physical boards for you. The expansion boards organize all of the external connections more neatly than on the standalone KL25Z, and they add all of the interface circuitry needed for all of the advanced software functions. The big thing they bring to the table is lots of high-power outputs. The boards provide a modular system that lets you add boards to add more outputs. If you opt for the basic core setup, you'll have enough outputs for all of the toys in a really well-equipped cabinet. If your ambitions go beyond merely well-equipped and run to the ridiculously extravagant, just add an extra board or two. The modular design also means that you can add to the system over time.

Expansion Board project page

Update notes

If you have a Pinscape V1 setup already installed, you should be able to switch to the new version pretty seamlessly. There are just a couple of things to be aware of.

First, the "configuration" procedure is completely different in the new version. Way better and way easier, but it's not what you're used to from V1. In V1, you had to edit the project source code and compile your own custom version of the program. No more! With V2, you simply install the standard, pre-compiled .bin file, and select options using the Pinscape Config Tool on Windows.

Second, if you're using the TSL1410R optical sensor for your plunger, there's a chance you'll need to boost your light source's brightness a little bit. The "shutter speed" is faster in this version, which means that it doesn't spend as much time collecting light per frame as before. The software actually does "auto exposure" adaptation on every frame, so the increased shutter speed really shouldn't bother it, but it does require a certain minimum level of contrast, which requires a certain minimal level of lighting. Check the plunger viewer in the setup tool if you have any problems; if the image looks totally dark, try increasing the light level to see if that helps.

New Features

V2 has numerous new features. Here are some of the highlights...

Dynamic configuration: as explained above, configuration is now handled through the Config Tool on Windows. It's no longer necessary to edit the source code or compile your own modified binary.

Improved plunger sensing: the software now reads the TSL1410R optical sensor about 15x faster than it did before. This allows reading the sensor at full resolution (400dpi), about 400 times per second. The faster frame rate makes a big difference in how accurately we can read the plunger position during the fast motion of a release, which allows for more precise position sensing and faster response. The differences aren't dramatic, since the sensing was already pretty good even with the slower V1 scan rate, but you might notice a little better precision in tricky skill shots.

Keyboard keys: button inputs can now be mapped to keyboard keys. The joystick button option is still available as well, of course. Keyboard keys have the advantage of being closer to universal for PC pinball software: some pinball software can be set up to take joystick input, but nearly all PC pinball emulators can take keyboard input, and nearly all of them use the same key mappings.

Local shift button: one physical button can be designed as the local shift button. This works like a Shift button on a keyboard, but with cabinet buttons. It allows each physical button on the cabinet to have two PC keys assigned, one normal and one shifted. Hold down the local shift button, then press another key, and the other key's shifted key mapping is sent to the PC. The shift button can have a regular key mapping of its own as well, so it can do double duty. The shift feature lets you access more functions without cluttering your cabinet with extra buttons. It's especially nice for less frequently used functions like adjusting the volume or activating night mode.

Night mode: the output controller has a new "night mode" option, which lets you turn off all of your noisy devices with a single button, switch, or PC command. You can designate individual ports as noisy or not. Night mode only disables the noisemakers, so you still get the benefit of your flashers, button lights, and other quiet devices. This lets you play late into the night without disturbing your housemates or neighbors.

Gamma correction: you can designate individual output ports for gamma correction. This adjusts the intensity level of an output to make it match the way the human eye perceives brightness, so that fades and color mixes look more natural in lighting devices. You can apply this to individual ports, so that it only affects ports that actually have lights of some kind attached.

IR Remote Control: the controller software can transmit and/or receive IR remote control commands if you attach appropriate parts (an IR LED to send, an IR sensor chip to receive). This can be used to turn on your TV(s) when the system powers on, if they don't turn on automatically, and for any other functions you can think of requiring IR send/receive capabilities. You can assign IR commands to cabinet buttons, so that pressing a button on your cabinet sends a remote control command from the attached IR LED, and you can have the controller generate virtual key presses on your PC in response to received IR commands. If you have the IR sensor attached, the system can use it to learn commands from your existing remotes.

Yet more USB fixes: I've been gradually finding and fixing USB bugs in the mbed library for months now. This version has all of the fixes of the last couple of releases, of course, plus some new ones. It also has a new "last resort" feature, since there always seems to be "just one more" USB bug. The last resort is that you can tell the device to automatically reboot itself if it loses the USB connection and can't restore it within a given time limit.

More Downloads

  • Custom VP builds: I created modified versions of Visual Pinball 9.9 and Physmod5 that you might want to use in combination with this controller. The modified versions have special handling for plunger calibration specific to the Pinscape Controller, as well as some enhancements to the nudge physics. If you're not using the plunger, you might still want it for the nudge improvements. The modified version also works with any other input controller, so you can get the enhanced nudging effects even if you're using a different plunger/nudge kit. The big change in the modified versions is a "filter" for accelerometer input that's designed to make the response to cabinet nudges more realistic. It also makes the response more subdued than in the standard VP, so it's not to everyone's taste. The downloads include both the updated executables and the source code changes, in case you want to merge the changes into your own custom version(s).

    Note! These features are now standard in the official VP releases, so you don't need my custom builds if you're using 9.9.1 or later and/or VP 10. I don't think there's any reason to use my versions instead of the latest official ones, and in fact I'd encourage you to use the official releases since they're more up to date, but I'm leaving my builds available just in case. In the official versions, look for the checkbox "Enable Nudge Filter" in the Keys preferences dialog. My custom versions don't include that checkbox; they just enable the filter unconditionally.
  • Output circuit shopping list: This is a saved shopping cart at with the parts needed to build one copy of the high-power output circuit for the LedWiz emulator feature, for use with the standalone KL25Z (that is, without the expansion boards). The quantities in the cart are for one output channel, so if you want N outputs, simply multiply the quantities by the N, with one exception: you only need one ULN2803 transistor array chip for each eight output circuits. If you're using the expansion boards, you won't need any of this, since the boards provide their own high-power outputs.
  • Cary Owens' optical sensor housing: A 3D-printable design for a housing/mounting bracket for the optical plunger sensor, designed by Cary Owens. This makes it easy to mount the sensor.
  • Lemming77's potentiometer mounting bracket and shooter rod connecter: Sketchup designs for 3D-printable parts for mounting a slide potentiometer as the plunger sensor. These were designed for a particular slide potentiometer that used to be available from an seller but is no longer listed. You can probably use this design as a starting point for other similar devices; just check the dimensions before committing the design to plastic.

Copyright and License

The Pinscape firmware is copyright 2014, 2021 by Michael J Roberts. It's released under an MIT open-source license. See License.

Warning to VirtuaPin Kit Owners

This software isn't designed as a replacement for the VirtuaPin plunger kit's firmware. If you bought the VirtuaPin kit, I recommend that you don't install this software. The VirtuaPin kit uses the same KL25Z microcontroller that Pinscape uses, but the rest of its hardware is different and incompatible. In particular, the Pinscape firmware doesn't include support for the IR proximity sensor used in the VirtuaPin plunger kit, so you won't be able to use your plunger device with the Pinscape firmware. In addition, the VirtuaPin setup uses a different set of GPIO pins for the button inputs from the Pinscape defaults, so if you do install the Pinscape firmware, you'll have to go into the Config Tool and reassign all of the buttons to match the VirtuaPin wiring.

Sat Apr 18 19:08:55 2020 +0000
TCD1103 DMA setup time padding to fix sporadic missed first pixel in transfer; fix TV ON so that the TV ON IR commands don't have to be grouped in the IR command first slots

Who changed what in which revision?

UserRevisionLine numberNew contents of line
mjr 86:e30a1f60f783 1 // Bit-bang I2C for KL25Z
mjr 86:e30a1f60f783 2 //
mjr 86:e30a1f60f783 3 // This implements an I2C interface that can operate on any KL25Z GPIO
mjr 86:e30a1f60f783 4 // ports, whether or not they're connected to I2C hardware on the MCU.
mjr 86:e30a1f60f783 5 // We simply send and receive bits using direct port manipulation (often
mjr 86:e30a1f60f783 6 // called "bit banging") instead of using the MCU I2C hardware. This
mjr 86:e30a1f60f783 7 // is more flexible than the mbed I2C class, since that only works with
mjr 86:e30a1f60f783 8 // a small number of pins, and there are only two I2C modules in the
mjr 86:e30a1f60f783 9 // system. This GPIO version can be to gain additional I2C ports if
mjr 86:e30a1f60f783 10 // the hardware I2C modules are committed to other purposes, or all of
mjr 86:e30a1f60f783 11 // the I2C-capable pins are being used for other purposes.
mjr 86:e30a1f60f783 12 //
mjr 86:e30a1f60f783 13 // The tradeoff for the added flexibility is that the hardware I2C is
mjr 86:e30a1f60f783 14 // faster. This implementation can take advantage of bus speeds up to
mjr 86:e30a1f60f783 15 // about 500kHz, which produces data rates of about 272 kbps. Higher
mjr 86:e30a1f60f783 16 // clock speeds are allowed, but the actual bit rate will plateau at
mjr 86:e30a1f60f783 17 // this level due to the performance constraints of the CPU (and of
mjr 86:e30a1f60f783 18 // this code itself; some additional performance could probably be
mjr 86:e30a1f60f783 19 // gained by optimizing it further). The KL25Z I2C hardware can double
mjr 86:e30a1f60f783 20 // our speed: it can achieve bus speeds of 1MHz and data rates of about
mjr 86:e30a1f60f783 21 // 540kbps. Of course, such high speeds can only be used with compatible
mjr 86:e30a1f60f783 22 // devices; many devices are limited to the "standard mode" at 100kHz or
mjr 86:e30a1f60f783 23 // "fast mode" at 400kHz, both of which we can fully saturate. However,
mjr 86:e30a1f60f783 24 // even at the slower bus speeds, the hardware I2C has another advantage:
mjr 86:e30a1f60f783 25 // it's capable of DMA operation. That's vastly superior for large
mjr 86:e30a1f60f783 26 // transactions since it lets the CPU do other work in parallel with
mjr 86:e30a1f60f783 27 // I2C bit movement.
mjr 82:4f6209cb5c33 28 //
mjr 86:e30a1f60f783 29 // This class isn't meant to be directly compatible with the mbed I2C
mjr 86:e30a1f60f783 30 // class, but we try to adhere to the mbed conventions and method names
mjr 86:e30a1f60f783 31 // to make it a mostly drop-in replacement. In particular, we use the
mjr 86:e30a1f60f783 32 // mbed library's "2X" device address convention. Most device data sheets
mjr 86:e30a1f60f783 33 // list the device I2C address in 7-bit format, so you'll have to shift
mjr 86:e30a1f60f783 34 // the nominal address from the data sheet left one bit in each call
mjr 86:e30a1f60f783 35 // to a routine here.
mjr 86:e30a1f60f783 36 //
mjr 87:8d35c74403af 37 // Electrically, the I2C bus consists of two lines, SDA (data) and SCL
mjr 87:8d35c74403af 38 // (clock). Multiple devices can connect to the bus by connecting to
mjr 87:8d35c74403af 39 // these two lines; the lines are shared among all of the devices. Each
mjr 87:8d35c74403af 40 // line has a pull-up resistor that pulls it to logic '1' voltage. Each
mjr 87:8d35c74403af 41 // device connects with an open-collector circuit that can short the line
mjr 87:8d35c74403af 42 // to ground (logic '0'). This means that any device can assert a 'low'
mjr 87:8d35c74403af 43 // but no one can actually assert a 'high'; the pull-up makes it so that
mjr 87:8d35c74403af 44 // a 'high' occurs when no one is asserting a 'low'. On an MCU, we release
mjr 87:8d35c74403af 45 // a line by putting the GPIO pin in high-Z state, which we can do on the
mjr 87:8d35c74403af 46 // KL25Z by setting its direction to INPUT mode. So our GPIO write strategy
mjr 87:8d35c74403af 47 // is like this:
mjr 86:e30a1f60f783 48 //
mjr 86:e30a1f60f783 49 // - take a pin low (0):
mjr 86:e30a1f60f783 50 // pin.input();
mjr 86:e30a1f60f783 51 // pin.write(0);
mjr 86:e30a1f60f783 52 //
mjr 86:e30a1f60f783 53 // - take a pin high (1):
mjr 86:e30a1f60f783 54 // pin.output();
mjr 86:e30a1f60f783 55 //
mjr 86:e30a1f60f783 56 // Note that we don't actually have to write the '0' on each pull low,
mjr 86:e30a1f60f783 57 // since we just leave the port output register set with '0'. Changing
mjr 86:e30a1f60f783 58 // the direction to output is enough to assert the low level, since the
mjr 86:e30a1f60f783 59 // hardware asserts the level that was previously stored in the output
mjr 86:e30a1f60f783 60 // register whenever the direction is changed from input to output.
mjr 87:8d35c74403af 61 //
mjr 87:8d35c74403af 62 // The KL25Z by default provides a built-in pull-up resistor on each GPIO
mjr 87:8d35c74403af 63 // set to input mode. This can optionally be used as the bus-wide pull-up
mjr 87:8d35c74403af 64 // for each line. Standard practice is to use external pull-up resistors
mjr 87:8d35c74403af 65 // rather than MCU pull-ups, but the internal pull-ups are fine for ad hoc
mjr 87:8d35c74403af 66 // setups where there's only one external device connected to a GPIO pair.
mjr 86:e30a1f60f783 67
mjr 82:4f6209cb5c33 68
mjr 82:4f6209cb5c33 69 #ifndef _BITBANGI2C_H_
mjr 82:4f6209cb5c33 70 #define _BITBANGI2C_H_
mjr 82:4f6209cb5c33 71
mjr 82:4f6209cb5c33 72 #include "mbed.h"
mjr 86:e30a1f60f783 73 #include "gpio_api.h"
mjr 86:e30a1f60f783 74 #include "pinmap.h"
mjr 86:e30a1f60f783 75
mjr 86:e30a1f60f783 76
mjr 87:8d35c74403af 77 // For testing purposes: a cover class for the mbed library I2C bridging
mjr 87:8d35c74403af 78 // the minor differences in our interface. This allows switching between
mjr 87:8d35c74403af 79 // BitBangI2C and the mbed library I2C via a macro of the like.
mjr 87:8d35c74403af 80 class MbedI2C: public I2C
mjr 87:8d35c74403af 81 {
mjr 87:8d35c74403af 82 public:
mjr 87:8d35c74403af 83 MbedI2C(PinName sda, PinName scl, bool internalPullups) : I2C(sda, scl) { }
mjr 87:8d35c74403af 84
mjr 87:8d35c74403af 85 int write(int addr, const uint8_t *data, size_t len, bool repeated = false)
mjr 87:8d35c74403af 86 {
mjr 87:8d35c74403af 87 return I2C::write(addr, (const char *)data, len, repeated);
mjr 87:8d35c74403af 88 }
mjr 87:8d35c74403af 89 int read(int addr, uint8_t *data, size_t len, bool repeated = false)
mjr 87:8d35c74403af 90 {
mjr 87:8d35c74403af 91 return I2C::read(addr, (char *)data, len, repeated);
mjr 87:8d35c74403af 92 }
mjr 87:8d35c74403af 93
mjr 87:8d35c74403af 94 void reset() { }
mjr 87:8d35c74403af 95 };
mjr 87:8d35c74403af 96
mjr 87:8d35c74403af 97
mjr 86:e30a1f60f783 98 // DigitalInOut replacmement class for I2C use. I2C uses pins a little
mjr 86:e30a1f60f783 99 // differently from other use cases. I2C is a bus, where many devices can
mjr 86:e30a1f60f783 100 // be attached to each line. To allow this shared access, devices can
mjr 86:e30a1f60f783 101 // only drive the line low. No device can drive the line high; instead,
mjr 86:e30a1f60f783 102 // the line is *pulled* high, by the attached pull-up resistors, when no
mjr 86:e30a1f60f783 103 // one is driving it low. As a result, we can't use the normal DigitalOut
mjr 86:e30a1f60f783 104 // write(), since that would try to actively drive the pin high on write(1).
mjr 86:e30a1f60f783 105 // Instead, write(1) needs to change the pin to high-impedance (high-Z)
mjr 86:e30a1f60f783 106 // state instead of driving it, which on the KL25Z is accomplished by
mjr 86:e30a1f60f783 107 // changing the port direction mode to INPUT. So:
mjr 86:e30a1f60f783 108 //
mjr 86:e30a1f60f783 109 // write(0) = direction->OUTPUT (pin->0)
mjr 86:e30a1f60f783 110 // write(1) = direction->INPUT
mjr 86:e30a1f60f783 111 //
mjr 86:e30a1f60f783 112 class I2CInOut
mjr 86:e30a1f60f783 113 {
mjr 86:e30a1f60f783 114 public:
mjr 87:8d35c74403af 115 I2CInOut(PinName pin, bool internalPullup)
mjr 86:e30a1f60f783 116 {
mjr 86:e30a1f60f783 117 // initialize the pin
mjr 86:e30a1f60f783 118 gpio_t g;
mjr 86:e30a1f60f783 119 gpio_init(&g, pin);
mjr 86:e30a1f60f783 120
mjr 86:e30a1f60f783 121 // get the registers
mjr 87:8d35c74403af 122 unsigned int portno = (unsigned int)pin >> PORT_SHIFT;
mjr 87:8d35c74403af 123 uint32_t pinno = (uint32_t)(pin & 0x7C) >> 2;
mjr 87:8d35c74403af 124 FGPIO_Type *r = (FGPIO_Type *)(FPTA_BASE + portno*0x40);
mjr 87:8d35c74403af 125 __IO uint32_t *pin_pcr = &(((PORT_Type *)(PORTA_BASE + 0x1000*portno)))->PCR[pinno];
mjr 86:e30a1f60f783 126
mjr 87:8d35c74403af 127 // set the desired internal pull-up mode
mjr 87:8d35c74403af 128 if (internalPullup)
mjr 87:8d35c74403af 129 *pin_pcr |= 0x02;
mjr 87:8d35c74403af 130 else
mjr 87:8d35c74403af 131 *pin_pcr &= ~0x02;
mjr 86:e30a1f60f783 132
mjr 86:e30a1f60f783 133 // save the register information we'll need later
mjr 86:e30a1f60f783 134 this->mask = g.mask;
mjr 86:e30a1f60f783 135 this->PDDR = &r->PDDR;
mjr 86:e30a1f60f783 136 this->PDIR = &r->PDIR;
mjr 86:e30a1f60f783 137
mjr 86:e30a1f60f783 138 // initially set as input to release the line
mjr 86:e30a1f60f783 139 r->PDDR &= ~mask;
mjr 86:e30a1f60f783 140
mjr 86:e30a1f60f783 141 // Set the output value to 0. It will always be zero, since
mjr 86:e30a1f60f783 142 // this is the only value we ever drive. When we want the port
mjr 86:e30a1f60f783 143 // to go high, we release it by changing the direction to input.
mjr 86:e30a1f60f783 144 r->PCOR = mask;
mjr 86:e30a1f60f783 145 }
mjr 86:e30a1f60f783 146
mjr 86:e30a1f60f783 147 // write a 1 (high) or 0 (low) value to the pin
mjr 86:e30a1f60f783 148 inline void write(int b) { if (b) hi(); else lo(); }
mjr 86:e30a1f60f783 149
mjr 86:e30a1f60f783 150 // Take the line high: set as input to put it in high-Z state so that
mjr 86:e30a1f60f783 151 // the pull-up resistor takes over.
mjr 86:e30a1f60f783 152 inline void hi() { *PDDR &= ~mask; }
mjr 86:e30a1f60f783 153
mjr 86:e30a1f60f783 154 // Take the line low: set as output to assert our '0' on the line and
mjr 86:e30a1f60f783 155 // pull it low. Note that we don't have to explicitly write the port
mjr 86:e30a1f60f783 156 // output register, since we initialized it with a '0' on our port and
mjr 86:e30a1f60f783 157 // never change it. The hardware will assert the level stored in the
mjr 86:e30a1f60f783 158 // register each time we change the direction to output, so there's no
mjr 86:e30a1f60f783 159 // need to write the port output register again each time.
mjr 86:e30a1f60f783 160 inline void lo() { *PDDR |= mask; }
mjr 86:e30a1f60f783 161
mjr 86:e30a1f60f783 162 // read the line
mjr 86:e30a1f60f783 163 inline int read()
mjr 86:e30a1f60f783 164 {
mjr 86:e30a1f60f783 165 *PDDR &= ~mask; // set as input
mjr 86:e30a1f60f783 166 return *PDIR & mask; // read the port
mjr 86:e30a1f60f783 167 }
mjr 86:e30a1f60f783 168
mjr 86:e30a1f60f783 169 // direction register
mjr 86:e30a1f60f783 170 volatile uint32_t *PDDR;
mjr 86:e30a1f60f783 171
mjr 86:e30a1f60f783 172 // input register
mjr 86:e30a1f60f783 173 volatile uint32_t *PDIR;
mjr 86:e30a1f60f783 174
mjr 86:e30a1f60f783 175 // pin mask
mjr 86:e30a1f60f783 176 uint32_t mask;
mjr 86:e30a1f60f783 177 };
mjr 86:e30a1f60f783 178
mjr 86:e30a1f60f783 179
mjr 86:e30a1f60f783 180
mjr 86:e30a1f60f783 181 // bit-bang I2C
mjr 82:4f6209cb5c33 182 class BitBangI2C
mjr 82:4f6209cb5c33 183 {
mjr 82:4f6209cb5c33 184 public:
mjr 82:4f6209cb5c33 185 // create the interface
mjr 87:8d35c74403af 186 BitBangI2C(PinName sda, PinName scl, bool internalPullups);
mjr 82:4f6209cb5c33 187
mjr 82:4f6209cb5c33 188 // set the bus frequency in Hz
mjr 86:e30a1f60f783 189 void frequency(uint32_t freq);
mjr 82:4f6209cb5c33 190
mjr 82:4f6209cb5c33 191 // set START condition on the bus
mjr 82:4f6209cb5c33 192 void start();
mjr 82:4f6209cb5c33 193
mjr 82:4f6209cb5c33 194 // set STOP condition on the bus
mjr 82:4f6209cb5c33 195 void stop();
mjr 82:4f6209cb5c33 196
mjr 82:4f6209cb5c33 197 // Write a series of bytes. Returns 0 on success, non-zero on failure.
mjr 82:4f6209cb5c33 198 // Important: 'addr' is 2X the nominal address - shift left by one bit.
mjr 82:4f6209cb5c33 199 int write(uint8_t addr, const uint8_t *data, size_t len, bool repeated = false);
mjr 82:4f6209cb5c33 200
mjr 82:4f6209cb5c33 201 // write a byte; returns true if ACK was received
mjr 82:4f6209cb5c33 202 int write(uint8_t data);
mjr 82:4f6209cb5c33 203
mjr 82:4f6209cb5c33 204 // Read a series of bytes. Returns 0 on success, non-zero on failure.
mjr 82:4f6209cb5c33 205 // Important: 'addr' is 2X the nominal address - shift left by one bit.
mjr 82:4f6209cb5c33 206 int read(uint8_t addr, uint8_t *data, size_t len, bool repeated = false);
mjr 82:4f6209cb5c33 207
mjr 82:4f6209cb5c33 208 // read a byte, optionally sending an ACK on receipt
mjr 82:4f6209cb5c33 209 int read(bool ack);
mjr 82:4f6209cb5c33 210
mjr 82:4f6209cb5c33 211 // wait for ACK; returns true if ACK was received
mjr 82:4f6209cb5c33 212 bool wait(uint32_t timeout_us);
mjr 82:4f6209cb5c33 213
mjr 82:4f6209cb5c33 214 // reset the bus
mjr 82:4f6209cb5c33 215 void reset();
mjr 82:4f6209cb5c33 216
mjr 82:4f6209cb5c33 217 protected:
mjr 82:4f6209cb5c33 218 // read/write a bit
mjr 82:4f6209cb5c33 219 int readBit();
mjr 86:e30a1f60f783 220
mjr 86:e30a1f60f783 221 // write a bit
mjr 86:e30a1f60f783 222 inline void writeBit(int bit)
mjr 86:e30a1f60f783 223 {
mjr 86:e30a1f60f783 224 // put the bit on the SDA line
mjr 86:e30a1f60f783 225 sdaPin.write(bit);
mjr 86:e30a1f60f783 226 hiResWait(tSuDat);
mjr 86:e30a1f60f783 227
mjr 86:e30a1f60f783 228 // clock it
mjr 86:e30a1f60f783 229 sclPin.hi();
mjr 87:8d35c74403af 230 hiResWait(tHigh);
mjr 86:e30a1f60f783 231
mjr 86:e30a1f60f783 232 // drop the clock
mjr 86:e30a1f60f783 233 sclPin.lo();
mjr 86:e30a1f60f783 234 hiResWait(tLow);
mjr 86:e30a1f60f783 235 }
mjr 82:4f6209cb5c33 236
mjr 82:4f6209cb5c33 237 // set SCL/SDA lines to high (1) or low(0)
mjr 86:e30a1f60f783 238 inline void scl(int level) { sclPin.write(level); }
mjr 86:e30a1f60f783 239 inline void sda(int level) { sdaPin.write(level); }
mjr 86:e30a1f60f783 240
mjr 86:e30a1f60f783 241 inline void sclHi() { sclPin.hi(); }
mjr 86:e30a1f60f783 242 inline void sclLo() { sclPin.lo(); }
mjr 86:e30a1f60f783 243 inline void sdaHi() { sdaPin.hi(); }
mjr 86:e30a1f60f783 244 inline void sdaLo() { sdaPin.lo(); }
mjr 82:4f6209cb5c33 245
mjr 87:8d35c74403af 246 // SDA and SCL pins
mjr 87:8d35c74403af 247 I2CInOut sdaPin;
mjr 86:e30a1f60f783 248 I2CInOut sclPin;
mjr 82:4f6209cb5c33 249
mjr 82:4f6209cb5c33 250 // inverse of frequency = clock period in microseconds
mjr 82:4f6209cb5c33 251 uint32_t clkPeriod_us;
mjr 86:e30a1f60f783 252
mjr 86:e30a1f60f783 253 // High-resolution wait. This provides sub-microsecond wait
mjr 86:e30a1f60f783 254 // times, to get minimum times for I2C events. With the ARM
mjr 86:e30a1f60f783 255 // compiler, this produces measured wait times as follows:
mjr 86:e30a1f60f783 256 //
mjr 86:e30a1f60f783 257 // n=0 104ns
mjr 86:e30a1f60f783 258 // n=1 167ns
mjr 86:e30a1f60f783 259 // n=2 271ns
mjr 86:e30a1f60f783 260 // n=3 375ns
mjr 86:e30a1f60f783 261 // n=4 479ns
mjr 86:e30a1f60f783 262 //
mjr 86:e30a1f60f783 263 // For n > 1, the wait time is 167ns + (n-1)*104ns.
mjr 86:e30a1f60f783 264 // These times take into account caller overhead to load the
mjr 86:e30a1f60f783 265 // wait time from a member variable. Callers getting the wait
mjr 86:e30a1f60f783 266 // time from a constant or stack variable will have different
mjr 86:e30a1f60f783 267 // results.
mjr 86:e30a1f60f783 268 inline void hiResWait(volatile int n)
mjr 86:e30a1f60f783 269 {
mjr 86:e30a1f60f783 270 while (n != 0)
mjr 86:e30a1f60f783 271 --n;
mjr 86:e30a1f60f783 272 }
mjr 86:e30a1f60f783 273
mjr 86:e30a1f60f783 274 // Figure the hiResWait() time for a given nanosecond time.
mjr 86:e30a1f60f783 275 // We use this during setup to precompute the wait times required
mjr 86:e30a1f60f783 276 // for various events at a given clock speed.
mjr 86:e30a1f60f783 277 int calcHiResWaitTime(int nanoseconds)
mjr 86:e30a1f60f783 278 {
mjr 86:e30a1f60f783 279 // the shortest wait time is 104ns
mjr 86:e30a1f60f783 280 if (nanoseconds <= 104)
mjr 86:e30a1f60f783 281 return 0;
mjr 86:e30a1f60f783 282
mjr 86:e30a1f60f783 283 // Above that, we work in 104ns increments with a base
mjr 86:e30a1f60f783 284 // of 167ns. We round at the halfway point, because we
mjr 86:e30a1f60f783 285 // assume there's always a little extra overhead in the
mjr 86:e30a1f60f783 286 // caller itself that will pad by at least one instruction
mjr 86:e30a1f60f783 287 // of 60ns, which is more than half our interval.
mjr 86:e30a1f60f783 288 return (nanoseconds - 167 + 52)/104 + 1;
mjr 86:e30a1f60f783 289 }
mjr 86:e30a1f60f783 290
mjr 86:e30a1f60f783 291 // Time delays for I2C events. I2C has minimum timing requirements
mjr 86:e30a1f60f783 292 // based on the clock speed. Some of these are as short as 50ns.
mjr 86:e30a1f60f783 293 // The mbed wait timer has microsecond resolution, which is much
mjr 86:e30a1f60f783 294 // too coarse for fast I2C clock speeds, so we implement our own
mjr 86:e30a1f60f783 295 // finer-grained wait.
mjr 86:e30a1f60f783 296 //
mjr 86:e30a1f60f783 297 // These are in hiResWait() units - see above.
mjr 86:e30a1f60f783 298 //
mjr 86:e30a1f60f783 299 int tLow; // SCL low period
mjr 86:e30a1f60f783 300 int tHigh; // SCL high period
mjr 86:e30a1f60f783 301 int tHdSta; // hold time for start condition
mjr 86:e30a1f60f783 302 int tSuSta; // setup time for repeated start condition
mjr 86:e30a1f60f783 303 int tSuSto; // setup time for stop condition
mjr 86:e30a1f60f783 304 int tSuDat; // data setup time
mjr 86:e30a1f60f783 305 int tAck; // ACK time
mjr 87:8d35c74403af 306 int tBuf; // bus free time between start and stop conditions
mjr 87:8d35c74403af 307
mjr 87:8d35c74403af 308 // are we in a Stop condition?
mjr 87:8d35c74403af 309 bool inStop;
mjr 82:4f6209cb5c33 310 };
mjr 82:4f6209cb5c33 311
mjr 82:4f6209cb5c33 312 #endif /* _BITBANGI2C_H_ */