xwiimote 2

- Main Page
- Modules
- Data Structures
- Files

Macros | Enumerations | Functions
Device Interface

Communication between applications and devices. More...

## Macros
#define | XWII_LED(num) (XWII_LED1 + (num) - 1)
| Create enum xwii_led constants during runtime. More...

## Enumerations
enum | xwii_iface_type { XWII_IFACE_CORE = 0x000001, XWII_IFACE_ACCEL = 0x000002, XWII_IFACE_IR = 0x000004, XWII_IFACE_MOTION_PLUS = 0x000100, XWII_IFACE_NUNCHUK = 0x000200, XWII_IFACE_CLASSIC_CONTROLLER = 0x000400, XWII_IFACE_BALANCE_BOARD = 0x000800, XWII_IFACE_PRO_CONTROLLER = 0x001000, XWII_IFACE_ALL, XWII_IFACE_WRITABLE = 0x010000 }
| Interfaces. More...
enum | xwii_led { XWII_LED1 = 1, XWII_LED2 = 2, XWII_LED3 = 3, XWII_LED4 = 4 }
| LEDs. More...

## Functions
int | xwii_iface_new (struct xwii_iface **dev, const char *syspath)
| Create new device object from syspath path. More...
void | xwii_iface_ref (struct xwii_iface *dev)
| Increase ref-count by 1. More...
void | xwii_iface_unref (struct xwii_iface *dev)
| Decrease ref-count by 1. More...
int | xwii_iface_get_fd (struct xwii_iface *dev)
| Return file-descriptor. More...
int | xwii_iface_watch (struct xwii_iface *dev, bool watch)
| Watch device for hotplug events. More...
int | xwii_iface_open (struct xwii_iface *dev, unsigned int ifaces)
| Open interfaces on this device. More...
void | xwii_iface_close (struct xwii_iface *dev, unsigned int ifaces)
| Close interfaces on this device. More...
unsigned int | xwii_iface_opened (struct xwii_iface *dev)
| Return bitmask of opened interfaces. More...
unsigned int | xwii_iface_available (struct xwii_iface *dev)
| Return bitmask of available interfaces. More...
XWII__DEPRECATED int | xwii_iface_poll (struct xwii_iface *dev, struct xwii_event *ev)
| Read incoming event-queue. More...
int | xwii_iface_dispatch (struct xwii_iface *dev, struct xwii_event *ev, size_t size)
| Read incoming event-queue. More...
int | xwii_iface_rumble (struct xwii_iface *dev, bool on)
| Toggle rumble motor. More...
int | xwii_iface_get_led (struct xwii_iface *dev, unsigned int led, bool *state)
| Read LED state. More...
int | xwii_iface_set_led (struct xwii_iface *dev, unsigned int led, bool state)
| Set LED state. More...
int | xwii_iface_get_battery (struct xwii_iface *dev, uint8_t *capacity)
| Read battery state. More...
int | xwii_iface_get_devtype (struct xwii_iface *dev, char **devtype)
| Read device type. More...
int | xwii_iface_get_extension (struct xwii_iface *dev, char **extension)
| Read extension type. More...
void | xwii_iface_set_mp_normalization (struct xwii_iface *dev, int32_t x, int32_t y, int32_t z, int32_t factor)
| Set MP normalization and calibration. More...
void | xwii_iface_get_mp_normalization (struct xwii_iface *dev, int32_t *x, int32_t *y, int32_t *z, int32_t *factor)
| Read MP normalization and calibration. More...

## Detailed Description

Communication between applications and devices.

The device interface provides a way to communicate with a connected remote device. It reads events from the device and provides them to the application. But it also allows applications to send events to devices.

Note that devices cannot be connected or searched for with this API. Instead, you should use your standard bluetooth tools to perform a bluetooth inquiry and connect devices. You do the same with bluetooth keyboards and mice, don't you?

If you want to enumerate connected devices and monitor the system for hotplug events, you should use the monitor interface or use libudev directly.

The device interface is split up into different sub-interfaces. Each of them is related to specific hardware available on the remote device. If some hardware is not present, the interfaces will not be provided to the application and will return -ENODEV.

Interfaces must be opened via xwii_iface_open() before you can use them. Once opened, they return events via the event stream which is accessed via xwii_iface_dispatch(). Furthermore, outgoing events can now be sent via the different helper functions. Some interfaces are static and don't need to be opened. You notice it if no XWII_IFACE_* constant is provided.

Once you are done with an interface, you should close it via xwii_iface_close(). The kernel can deactivate unused hardware to safe energy. If you keep them open, the kernel keeps them powered up.

## Macro Definition Documentation

#define XWII_LED | ( |  | num | ) | (XWII_LED1 + (num) - 1)

Create enum xwii_led constants during runtime.

The argument is a number starting with 1. So XWII_LED([num]) produces the same value as the constant XWII_LED[num] defined in enum xwii_led.

## Enumeration Type Documentation

enum xwii_iface_type

Interfaces.

Each constant describes a single interface. These are bit-masks that can be binary-ORed. If an interface does not provide such a constant, it is static and can be used without opening/closing it.

Enumerator
XWII_IFACE_CORE | Core interface.
XWII_IFACE_ACCEL | Accelerometer interface.
XWII_IFACE_IR | IR interface.
XWII_IFACE_MOTION_PLUS | MotionPlus extension interface.
XWII_IFACE_NUNCHUK | Nunchuk extension interface.
XWII_IFACE_CLASSIC_CONTROLLER | ClassicController extension interface.
XWII_IFACE_BALANCE_BOARD | BalanceBoard extension interface.
XWII_IFACE_PRO_CONTROLLER | ProController extension interface.
XWII_IFACE_ALL | Special flag ORed with all valid interfaces.
XWII_IFACE_WRITABLE | Special flag which causes the interfaces to be opened writable.

enum xwii_led

LEDs.

One constant for each Player-LED.

## Function Documentation

int xwii_iface_new | ( | struct xwii_iface ** | dev,
|  | const char * | syspath
| ) |  |

Create new device object from syspath path.

Parameters

  [out] | dev | Pointer to new opaque device is stored here
  [in] | syspath | Sysfs path to root device node

Creates a new device object. No interfaces on the device are opened by default. `syspath` must be a valid path to a wiimote device, either retrieved via a monitor object or via udev. It must point to the hid device, which is normally /sys/bus/hid/devices/[dev].

If this function fails, `dev` is not touched at all (and not cleared!). A new object always has an initial ref-count of 1.

Returns
  0 on success, negative error code on failure

void xwii_iface_ref | ( | struct xwii_iface * | dev | ) |

Increase ref-count by 1.

Parameters

  [in] | dev | Valid device object

void xwii_iface_unref | ( | struct xwii_iface * | dev | ) |

Decrease ref-count by 1.

Parameters

  [in] | dev | Valid device object

If the ref-count drops below 1, the object is destroyed immediately. All open interfaces are automatically closed and all allocated objects released when the object is destroyed.

int xwii_iface_get_fd | ( | struct xwii_iface * | dev | ) |

Return file-descriptor.

Parameters

  [in] | dev | Valid device object

Return the file-descriptor used by this device. If multiple file-descriptors are used internally, they are multi-plexed through an epoll descriptor. Therefore, this always returns the same single file-descriptor. You need to watch this for readable-events (POLLIN/EPOLLIN) and call xwii_iface_dispatch() whenever it is readable.

This function always returns a valid file-descriptor.

int xwii_iface_watch | ( | struct xwii_iface * | dev,
|  | bool | watch
| ) |  |

Watch device for hotplug events.

Parameters

  [in] | dev | Valid device object
  [in] | watch | Whether to watch for hotplug events or not

Toggle whether hotplug events should be reported or not. By default, no hotplug events are reported so this is off.

Note that this requires a separate udev-monitor for each device. Therefore, if your application uses its own udev-monitor, you should instead integrate the hotplug-detection into your udev-monitor.

Returns
  0 on success, negative error code on failure

int xwii_iface_open | ( | struct xwii_iface * | dev,
|  | unsigned int | ifaces
| ) |  |

Open interfaces on this device.

Parameters

  [in] | dev | Valid device object
  [in] | ifaces | Bitmask of interfaces of type enum xwii_iface_type

Open all the requested interfaces. If XWII_IFACE_WRITABLE is also set, the interfaces are opened with write-access. Note that interfaces that are already opened are ignored and not touched. If any interface fails to open, this function still tries to open the other requested interfaces and then returns the error afterwards. Hence, if this function fails, you should use xwii_iface_opened() to get a bitmask of opened interfaces and see which failed (if that is of interest).

Note that interfaces may be closed automatically during runtime if the kernel removes the interface or on error conditions. You always get an XWII_EVENT_WATCH event which you should react on. This is returned regardless whether xwii_iface_watch() was enabled or not.

Returns
  0 on success, negative error code on failure.

void xwii_iface_close | ( | struct xwii_iface * | dev,
|  | unsigned int | ifaces
| ) |  |

Close interfaces on this device.

Parameters

  [in] | dev | Valid device object
  [in] | ifaces | Bitmask of interfaces of type enum xwii_iface_type

Close the requested interfaces. This never fails.

unsigned int xwii_iface_opened | ( | struct xwii_iface * | dev | ) |

Return bitmask of opened interfaces.

Parameters

  [in] | dev | Valid device object

Returns a bitmask of opened interfaces. Interfaces may be closed due to error-conditions at any time. However, interfaces are never opened automatically.

You will get notified whenever this bitmask changes, except on explicit calls to xwii_iface_open() and xwii_iface_close(). See the XWII_EVENT_WATCH event for more information.

unsigned int xwii_iface_available | ( | struct xwii_iface * | dev | ) |

Return bitmask of available interfaces.

Parameters

  [in] | dev | Valid device object

Return a bitmask of available devices. These devices can be opened and are guaranteed to be present on the hardware at this time. If you watch your device for hotplug events (see xwii_iface_watch()) you will get notified whenever this bitmask changes. See the XWII_EVENT_WATCH event for more information.

XWII__DEPRECATED int xwii_iface_poll | ( | struct xwii_iface * | dev,
|  | struct xwii_event * | ev
| ) |  |

Read incoming event-queue.

Parameters

  [in] | dev | Valid device object
  [out] | ev | Pointer where to store a new event or NULL

You should call this whenever the file-descriptor returned by xwii_iface_get_fd() is reported as being readable. This function will perform all non-blocking outstanding tasks and then return.

This function always performs any background tasks and outgoing event-writes if they don't block. It returns an error if they fail. If `ev` is NULL, this function returns 0 on success after this has been done.

If `ev` is non-NULL, this function then tries to read a single incoming event. If no event is available, it returns -EAGAIN and you should watch the file-desciptor again until it is readable. Otherwise, you should call this function in a row as long as it returns 0. It stores the event in `ev` which you can then handle in your application.

Returns
  0 on success, -EAGAIN if no event can be read and `ev` is non-NULL and a negative error-code on failure

int xwii_iface_dispatch | ( | struct xwii_iface * | dev,
|  | struct xwii_event * | ev,
|  | size_t | size
| ) |  |

Read incoming event-queue.

Parameters

  [in] | dev | Valid device object
  [out] | ev | Pointer where to store a new event or NULL
  [in] | size | Size of `ev` if `ev` is non-NULL

You should call this whenever the file-descriptor returned by xwii_iface_get_fd() is reported as being readable. This function will perform all non-blocking outstanding tasks and then return.

This function always performs any background tasks and outgoing event-writes if they don't block. It returns an error if they fail. If `ev` is NULL, this function returns 0 on success after this has been done.

If `ev` is non-NULL, this function then tries to read a single incoming event. If no event is available, it returns -EAGAIN and you should watch the file-desciptor again until it is readable. Otherwise, you should call this function in a row as long as it returns 0. It stores the event in `ev` which you can then handle in your application.

This function is the successor or xwii_iface_poll(). It takes an additional `size` argument to provide backwards compatibility.

Returns
  0 on success, -EAGAIN if no event can be read and `ev` is non-NULL and a negative error-code on failure

int xwii_iface_rumble | ( | struct xwii_iface * | dev,
|  | bool | on
| ) |  |

Toggle rumble motor.

Parameters

  [in] | dev | Valid device object
  [in] | on | New rumble motor state

Toggle the rumble motor. This requires the core-interface to be opened in writable mode.

Returns
  0 on success, negative error code on failure.

int xwii_iface_get_led | ( | struct xwii_iface * | dev,
|  | unsigned int | led,
|  | bool * | state
| ) |  |

Read LED state.

Parameters

  [in] | dev | Valid device object
  [in] | led | LED constant defined in enum xwii_led
  [out] | state | Pointer where state should be written to

Reads the current LED state of the given LED. `state` will be either true or false depending on whether the LED is on or off.

LEDs are a static interface that does not have to be opened first.

Returns
  0 on success, negative error code on failure

int xwii_iface_set_led | ( | struct xwii_iface * | dev,
|  | unsigned int | led,
|  | bool | state
| ) |  |

Set LED state.

Parameters

  [in] | dev | Valid device object
  [in] | led | LED constant defined in enum xwii_led
  [in] | state | State to set on the LED

Changes the current LED state of the given LED. This has immediate effect.

LEDs are a static interface that does not have to be opened first.

Returns
  0 on success, negative error code on failure

int xwii_iface_get_battery | ( | struct xwii_iface * | dev,
|  | uint8_t * | capacity
| ) |  |

Read battery state.

Parameters

  [in] | dev | Valid device object
  [out] | capacity | Pointer where state should be written to

Reads the current battery capacity and write it into `capacity`. This is a value between 0 and 100, which describes the current capacity in per-cent.

Batteries are a static interface that does not have to be opened first.

Returns
  0 on success, negative error code on failure

int xwii_iface_get_devtype | ( | struct xwii_iface * | dev,
|  | char ** | devtype
| ) |  |

Read device type.

Parameters

  [in] | dev | Valid device object
  [out] | devtype | Pointer where the device type should be stored

Reads the current device-type, allocates a string and stores a pointer to the string in `devtype`. You must free it via free() after you are done.

This is a static interface that does not have to be opened first.

Returns
  0 on success, negative error code on failure

int xwii_iface_get_extension | ( | struct xwii_iface * | dev,
|  | char ** | extension
| ) |  |

Read extension type.

Parameters

  [in] | dev | Valid device object
  [out] | extension | Pointer where the extension type should be stored

Reads the current extension type, allocates a string and stores a pointer to the string in `extension`. You must free it via free() after you are done.

This is a static interface that does not have to be opened first.

Returns
  0 on success, negative error code on failure

void xwii_iface_set_mp_normalization | ( | struct xwii_iface * | dev,
|  | int32_t | x,
|  | int32_t | y,
|  | int32_t | z,
|  | int32_t | factor
| ) |  |

Set MP normalization and calibration.

Parameters

  [in] | dev | Valid device object
  [in] | x | x-value to use or 0
  [in] | y | y-value to use or 0
  [in] | z | z-value to use or 0
  [in] | factor | factor-value to use or 0

Set MP-normalization and calibration values. The Motion-Plus sensor is very sensitive and may return really crappy values. This interfaces allows to apply 3 absolute offsets x, y and z which are subtracted from any MP data before it is returned to the application. That is, if you set these values to 0, this has no effect (which is also the initial state).

The calibration factor `factor` is used to perform runtime calibration. If it is 0 (the initial state), no runtime calibration is performed. Otherwise, the factor is used to re-calibrate the zero-point of MP data depending on MP input. This is an angoing calibration which modifies the internal state of the x, y and z values.

void xwii_iface_get_mp_normalization | ( | struct xwii_iface * | dev,
|  | int32_t * | x,
|  | int32_t * | y,
|  | int32_t * | z,
|  | int32_t * | factor
| ) |  |

Read MP normalization and calibration.

Parameters

  [in] | dev | Valid device object
  [out] | x | Pointer where to store x-value or NULL
  [out] | y | Pointer where to store y-value or NULL
  [out] | z | Pointer where to store z-value or NULL
  [out] | factor | Pointer where to store factor-value or NULL

Reads the MP normalization and calibration values. Please see xwii_iface_set_mp_normalization() how this is handled.

Note that if the calibration factor is not 0, the normalization values may change depending on incoming MP data. Therefore, the data read via this function may differ from the values that you wrote to previously. However, apart from applied calibration, these value are the same as were set previously via xwii_iface_set_mp_normalization() and you can feed them back in later.