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.

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation