=head1 REST API

This document defines the REST API.  By and large, this follows the WebIOpi 
REST interface:

  https://code.google.com/p/webiopi/wiki/INSTALL?tm=6

There are a few notable differences, mostly to account for being on more 
than just the Rapsberry Pi.  For instance, the pcDuino has different 
voltage and bit resolutions for some of its ADC and PWM channels, so 
the API to access that data must specify a pin.

Specific differences are noted as "B<COMPATIBILITY NOTE>" below.

=head2 Status Codes

Just a few of the HTTP status codes you might expect to hit.

400 Bad Request (path incomplete)
403 GPIO # Not Available
403 GPIO # Disabled
404 [something] Not Found 


=head2 BASIC

=head3 GET /map

Returns a JSON list, with each entry corresponding to a pin on the physical 
header.  Each entry can be:

=over 4

=item * Some number (corresponding to a GPIO number)

=item * "V33" (3.3 volt power)

=item * "V50" (5.0 volt power)

=item * "GND" (ground)

=back

Example:

    ["V33", "V50", 2, "V50", 3, "GND", 4, 14, "GND", 15, 17, 18, 27, "GND", 22, 23, "V33", 24, 10, "GND", 9, 25, 11, 8, "GND", 7]

=head3 GET /*

Returns a JSON of available interfaces.  Keys:

=over 4

=item * UART [bool]

=item * SPI [bool]

=item * I2C [bool]

=item * ONEWIRE [bool]

=item * GPIO [object]

=back

GPIO's keys are numbers mapping to each GPIO pin.  The values are objects 
containing:

=over 4

=item * function ["IN", "OUT", "ALTn" (where n is some number)]

=item * value [bool]

=back

Example: 

    {
        "UART": 1, 
        "SPI": 0, 
        "I2C": 0, 
        "ONEWIRE": 0, 
        "GPIO": {
            "0": {"function": "IN", "value": 1}, 
            "1": {"function": "IN", "value": 1}, 
            "2": {"function": "IN", "value": 1}, 
            "3": {"function": "IN", "value": 1}, 
            "4": {"function": "IN", "value": 1}, 
            "5": {"function": "IN", "value": 1}, 
            "6": {"function": "IN", "value": 1}, 
            "7": {"function": "ALT0", "value": 1},
            "8": {"function": "ALT0", "value": 1},
            "9": {"function": "ALT0", "value": 0},
            "10": {"function": "ALT0", "value": 0}, "11": {"function": "ALT0", "value": 0}, "12": {"function": "IN", "value": 0}, "13": {"function": "IN", "value": 0}, "14": {"function": "ALT0", "value": 1}, "15": {"function": "ALT0", "value": 1}, "16": {"function": "IN", "value": 0}, "17": {"function": "IN", "value": 0}, "18": {"function": "IN", "value": 0}, "19": {"function": "IN", "value": 0}, "20": {"function": "IN", "value": 0}, "21": {"function": "IN", "value": 0}, "22": {"function": "IN", "value": 0}, "23": {"function": "IN", "value": 0}, "24": {"function": "IN", "value": 0}, "25": {"function": "IN", "value": 0}, "26": {"function": "IN", "value": 0}, "27": {"function": "IN", "value": 0}, "28": {"function": "IN", "value": 1}, "29": {"function": "IN", "value": 1}, "30": {"function": "IN", "value": 0}, "31": {"function": "OUT", "value": 1}, "32": {"function": "OUT", "value": 0}, "33": {"function": "IN", "value": 0}, "34": {"function": "IN", "value": 1}, "35": {"function": "IN", "value": 1}, "36": {"function": "IN", "value": 1}, "37": {"function": "IN", "value": 0}, "38": {"function": "OUT", "value": 0}, "39": {"function": "IN", "value": 0}, "40": {"function": "ALT0", "value": 0}, "41": {"function": "OUT", "value": 0}, "42": {"function": "IN", "value": 0}, "43": {"function": "IN", "value": 0}, "44": {"function": "ALT0", "value": 1}, "45": {"function": "ALT0", "value": 0}, "46": {"function": "IN", "value": 1}, "47": {"function": "OUT", "value": 0}, "48": {"function": "ALT3", "value": 1}, "49": {"function": "ALT3", "value": 1}, "50": {"function": "ALT3", "value": 1}, "51": {"function": "ALT3", "value": 1}, "52": {"function": "ALT3", "value": 1}, "53": {"function": "ALT3", "value": 1}}}

=head2 GPIO

=head3 GET /devices/[name]/count

Returns the digital channel count

=head3 GET /devices/[name]/[channel]/value

Returns the value of the given digital channel

=head3 GET /devices/[name]/*/value

Returns a list of values of all digital channels

(Return as CSV list?)

(B<COMPATIBILITY NOTE>: This is in the WebIOpi docs as POST)

=head3 POST /devices/[name]/[channel]/value/[digit]

Sets the value of the digital channel

=head3 GET /devices/[name]/*/integer

Return an integer of all digital bits

=head3 POST /devices/[name]/*/integer/[value]

Write an integer for all digital bits

=head3 GET /devices/[name]/[channel]/function

Returns the current function of the given channel ("IN" or "OUT"(?))

=head3 POST /devices/[name]/[channel]/function/[func]

Sets the function of the given digital channel.

setFunctionString()

(B<COMPATIBILITY NOTE>: This is in the WebIOpi docs as GET)

=head3 GET /devices/[name]/*

Returns a list containing the value and function of all digital channels.

(Return as CSV list?)


=head2 ADC (Analog-to-Digital Converter)

=head3 GET /devices/[name]/analog/count

(B<NOTE>: Redundant listings in WebIOpi docs for analogCount and 
analogResolution)

=head3 GET /devices/[name]/analog/maximum

B<DEPRECATED>.  Return the maximum integer value of channel 0.

This is retained for compatibility with the original WebIOPi.  Since different 
pins can have different values, you should use the version that specifies a 
pin instead.

=head3 GET /devices/[name]/analog/[channel]/maximum

Return the maximum integer value of the given channel.

analogMaximum()

=head3 GET /devices/[name]/analog/integer/vref

B<DEPRECATED>.  Return the voltage reference of channel 0.

This is retained for compatibility with the original WebIOPi.  Since different 
pins can have different values, you should use the version that specifies a 
pin instead.

=head3 GET /devices/[name]/analog/[channel]/integer/vref

Return the voltage reference of the given channel.

analogReference()

=head3 GET /devices/[name]/analog/[channel]/integer

=head3 GET /devices/[name]/analog/[channel]/float

=head3 GET /devices/[name]/analog/[channel]/volt

=head3 GET /devices/[name]/analog/*/integer

analogReadAll()

(list returned as CSV?)

=head3 GET /devices/[name]/analog/*/float

(list returned as CSV?)


=head2 DAC (Digital-to-Analog Converter)

Extends ADC interface

=head3 POST /devices/[name]/analog/[channel]/integer/[value]

=head3 POST /devices/[name]/analog/[channel]/float/[value]

=head3 POST /devices/[name]/analog/[channel]/volt/[value]

=head2 PWM (Pulse Width Modulation)

=head3 GET /devices/[name]/pwm/count

=head3 GET /devices/[name]/pwm/resolution

B<DEPRECATED>.  Return the PWM resolution of channel 0.

This is retained for compatibility with the original WebIOPi.  Since different 
pins can have different values, you should use the version that specifies a 
pin instead.

=head3 GET /devices/[name]/pwm/[channel]/resolution

Return the PWM resolution of the given channel.

pwmResolution()

=head3 GET /devices/[name]/pwm/maximum

B<DEPRECATED>.  Return the PWM maximum integer value of channel 0.

This is retained for compatibility with the original WebIOPi.  Since different 
pins can have different values, you should use the version that specifies a 
pin instead.

=head3 GET /devices/[name]/pwm/[channel]/maximum

Return the PWM maximum integer value of the given channel.

pwmMaximum()

(B<COMPATIBILITY NOTE>: WebIOpi does not use channel argument)

=head3 POST /devices/[name]/pwm/[channel]/integer/[value]

=head3 POST /devices/[name]/pwm/[channel]/float/[value]

=head3 POST /devices/[name]/pwm/[channel]/angle/[value]

=head3 GET /devices/[name]/pwm/[channel]/integer

=head3 GET /devices/[name]/pwm/[channel]/float

=head3 GET /devices/[name]/pwm/[channel]/angle

=head3 GET /devices/[name]/pwm/*/integer

=head3 GET /devices/[name]/pwm/*/float

=head3 GET /devices/[name]/pwm/*/angle

=head3 GET /devices/[name]/pwm/*


=head2 VideoStream

B<COMPATIBILITY NOTE>: This is an extension which is not currently 
implemented in WebIOPi

=head3 GET /devices/[name]/video/count

Returns the number of video streams that are available.

=head3 GET /devices/[name]/video/[channel]/resolution

Returns the width and height separated by an I<x> list, followed by a 
I<p>, followed the fps.  Example:

  640x480p60

=head3 POST /devices/[name]/video/[channel]/resolution/[width]/[height]/[fps]

Sets the resolution and frame rate of the given channel.

If the channel refuses to set the given resolution, HTTP status code 403 
will be sent.

=head3 GET /devices/[name]/video/[channel]/kbps

Get the current bitrate, as an integer in kb per second.

=head3 POST /devices/[name]/video/[channel]/kbps/[value]

Set the current bitrate.  C<[value]> is an integer in kb per second.

=head3 GET /devices/[name]/video/[channel]/allowed-content-types

Get list of allowed MIME content types.  Allowed types will be sent as a 
MIME string, with one on each line.

=head3 GET /devices/[name]/video/[channel]/stream/[content-type1]/[content-type2]

Get the video stream with the desired content type.

B<NOTE>: [content-type1]/[content-type2] is really just a straight MIME 
type, like "text/video".  It's split up this way for the sake of 
popular server-side web libraries.


=head2 Still Images

B<COMPATIBILITY NOTE>: This is an extension which is not currently 
implemented in WebIOPi

=head3 GET /devices/[name]/image/count

Returns the number of image streams that are available.

=head3 GET /devices/[name]/image/[channel]/resolution

Returns the width and height separated by an I<x> list.  Example:

  640x480

=head3 POST /devices/[name]/image/[channel]/resolution/[width]/[height]

Sets the resolution of the given channel.

If the channel refuses to set the given resolution, HTTP status code 403 
will be sent.

=head3 GET /devices/[name]/image/[channel]/allowed-content-types

Get list of allowed MIME content types.  Allowed types will be sent as a 
MIME string, with one on each line.

=head3 GET /devices/[name]/image/[channel]/stream/[content-type1]/[content-type2]

Get the image with the desired content type.

B<NOTE>: [content-type1]/[content-type2] is really just a straight MIME 
type, like "text/video".  It's split up this way for the sake of 
popular server-side web libraries.


=head2 SPI

=head2 I2C

=head2 OneWire

=head2 Pressure

=head2 Luminosity

=head2 Distance


=end
