Difference between revisions of "Project:USB Disco Dance Floor/v1/firmware"

From London Hackspace Wiki
Jump to navigation Jump to search
(Added skeleton for other commands, and note about ping response)
(Added full doc in comment at the end until I have time to transfer it to wikitext)
Line 152: Line 152:
 
|colspan="2"|???
 
|colspan="2"|???
 
|}
 
|}
 +
 +
<!--
 +
 +
Code | Action
 +
=====+========================================================================
 +
                          STATUS/DIAGNOSTIC COMMANDS
 +
-----+------------------------------------------------------------------------
 +
00  | Reset                                                            v1.0
 +
    | Resets the board to an initial state, with all pixels off. The board
 +
    | sends four bytes representing its hardware and firmware version (2
 +
    | each), followed by 2 bytes for hardware details. The high nybble of
 +
    | the first hardware info byte is the number of different colours
 +
    | supported (0x1, 0x3 or 0x4) and the low nibble is whether sensors are
 +
    | supported (0x1 for yes). The high nybble of the second byte specifies
 +
    | the number of bits needed to specify LED brightness (if different for
 +
    | different colours, the firmware will scale as necessary) and the low
 +
    | nybble does the same for sensor resolution. Note that, for the time
 +
    | being, resolutions should be a power of 2 (0x1, 0x2, 0x4, 0x8). This
 +
    | comand also resets the stored board ID to 0xFFFF (unset).
 +
-----+------------------------------------------------------------------------
 +
01  | Identify                                                          v1.0
 +
    | Informs the board of its board ID for this session (two bytes). Note
 +
    | that board IDs 0x0000 and 0xFFFF are reserved. The board responds with
 +
    | 0x00 (success).
 +
-----+------------------------------------------------------------------------
 +
02  | Ping                                                              v1.0
 +
    | Checks connectivity. The board will respond with 0x00 (success).
 +
-----+------------------------------------------------------------------------
 +
03  | Neighbours                                                        v1.2?
 +
    | Asks the board to search for its immediate neighbours. The board will
 +
    | respond with 8 bytes representing the two-byte IDs of its neighbours,
 +
    | starting with its "top" connection and proceeding clockwise. If no
 +
    | neighbour is found in a given position, 0x0000 is returned. If a
 +
    | neighbour is found but it has not been given an identifier for this
 +
    | session, it will return 0xFFFF.
 +
    | This should allow the controller software to automatically detect the
 +
    | layout of the floor.
 +
-----+------------------------------------------------------------------------
 +
0E  | Display static test pattern                                      v1.0
 +
    | A static test pattern will be displayed, as selected by the one-byte
 +
    | argument. A list of patterns is given below:
 +
    |  00 - All white
 +
    |  01 - All red
 +
    |  02 - All green
 +
    |  03 - All yellow
 +
    |  04 - All blue
 +
    |  05 - All magenta
 +
    |  06 - All cyan
 +
    |  07 - All 50% white
 +
    |  08 - Checkerboard: (0,0)=red; (0,1)=cyan
 +
    |  09 - Checkerboard: (0,0)=cyan; (0,1)=red
 +
    |  0A - Checkerboard: (0,0)=green; (0,1)=magenta
 +
    |  0B - Checkerboard: (0,0)=magenta; (0,1)=green
 +
    |  0C - Checkerboard: (0,0)=blue; (0,1)=yellow
 +
    |  0D - Checkerboard: (0,0)=yellow; (0,1)=blue
 +
    |  0E - Checkerboard: (0,0)=white; (0,1)=black
 +
    |  0F - Checkerboard: (0,0)=black; (0,1)=white
 +
    |  10 - RGB fade, (0,0) = red; (3,0) = green; (0,3) = blue; (3,3) = ?
 +
-----+------------------------------------------------------------------------
 +
0F  | Display animated test pattern                                    v1.0
 +
    | An animated test pattern will be displayed, as selected by the one-byte
 +
    | argument. A list of patterns is given below:
 +
    |  00 - clockwise spiral chase (white), starting at (0,0)
 +
    |  01 - clockwise spiral (white), starting at (0,0); then black spiral
 +
    |      once complete
 +
==============================================================================
 +
                          SIMPLE DISPLAY COMMANDS
 +
-----+------------------------------------------------------------------------
 +
10  | Clear floor                                                      v1.0
 +
-----+------------------------------------------------------------------------
 +
11  | Write floor                                                      v1.0
 +
-----+------------------------------------------------------------------------
 +
18  | Clear row                                                        v1.0
 +
-----+------------------------------------------------------------------------
 +
19  | Write row                                                        v1.0
 +
==============================================================================
 +
                          COMPLEX DISPLAY COMMANDS
 +
-----+------------------------------------------------------------------------
 +
50  | Set pixel                                                        v1.1
 +
    | Should only be used very rarely, as it's highly data-inefficient.
 +
    | Sends a one-byte co-ordinate followed by a color specification. The low
 +
    | nybble of the co-ordinate is ignored.
 +
-----+------------------------------------------------------------------------
 +
51  | Draw line                                                        v1.1
 +
    | Sends a one-byte co-ordinate followed by a color specification. A
 +
    | 1-pixel line is drawn from absolute co-ordinates (x,y) to absolute
 +
    | co-ordinates (w,h) using ???'s algorithm.
 +
-----+------------------------------------------------------------------------
 +
52  | Draw hollow rectangle                                            v1.1
 +
    | Sends a one-byte co-ordinate followed by a color specification. A
 +
    | hollow rectangle will be drawn of width w and height h, with top-left
 +
    | at (x, y).
 +
-----+------------------------------------------------------------------------
 +
53  | Draw filled rectangle                                            v1.1
 +
    | Sends a one-byte co-ordinate followed by a color specification. A
 +
    | filled rectangle will be drawn of width w and height h, with top-left
 +
    | at (x, y).
 +
-----+------------------------------------------------------------------------
 +
54  | Scroll floor                                                      v1.1
 +
    | Sends a one-byte co-ordinate. Scrolls the entire image by (x, y)
 +
    | pixels. If w or h is non-zero then the scroll direction is reversed.
 +
-----+------------------------------------------------------------------------
 +
55  | Scroll rectangle                                                  v1.1
 +
    | Sends two co-ordinate bytes. The first defines the rectangle to scroll,
 +
    | the second is a scroll spec (as above).
 +
-----+------------------------------------------------------------------------
 +
5E  | Draw single-colour pattern                                        v1.1
 +
    | Sends two bytes followed by a colour spec. The first two bytes define
 +
    | the pattern to be drawn on the module as a whole, with set bits
 +
    | indicating that the given pixel should be set to the given colour.
 +
-----+------------------------------------------------------------------------
 +
5F  | Draw pattern rect                                                v1.1
 +
    | Sends a co-ordinate byte to define the rectangle, followed by a list of
 +
    | colour specs to be used when filling that rectangle. The specs are
 +
    | given in order of increasing X then increasing Y (e.g. (0,0), (1,0),
 +
    | (0,1), (1,0))
 +
 +
 +
Co-ordinates
 +
------------
 +
 +
Co-ordinates are specified as four two-bit values packed into a single byte:
 +
xxyywwhh
 +
 +
Scroll spec
 +
-----------
 +
 +
A scroll spec is specified as two two-bit values plus two one-bit values
 +
packed into a single byte: xxyy0w0h. The scroll amount in the X and Y axes is
 +
set by xx and yy, and if w/h are one the direction is reversed.
 +
 +
Colour specification
 +
--------------------
 +
 +
The board will report how many colours it supports at reset time. One colour
 +
will be referred to here as "R", three as "RGB" and four as "RGBU". The board
 +
also sends the number of bits that it can use for setting each colour
 +
brightness (n). Combining these parameters gives us a colour specification.
 +
 +
The colour spec consists of n bits of R, followed by n bits of G, B and U (as
 +
appropriate). If the number of bits is not a multiple of 8, it will be
 +
right-padded with zeroes.
 +
-->

Revision as of 17:56, 4 April 2011

USB Disco Dance Floor v1 Firmware
Created 2011-03-31
Members DMI
Project Status Prototyping


Introduction

The firmware will be responsible for listening for serial commands, and then acting upon them. This will primarily involve changing the display.

Data types

Colour spec

The board reports the number of colours it supports at reset time. The colour(s) in a one-colour board will be referred to as R, in a three-colour board as RGB, and in a four-colour board as RGBU. This is because of the suggested LED choices of Red, Green, Blue, and Ultraviolet. The board also reports the number of bits (n) that it can use for setting the brightness of each colour LED.

A colour spec consists of n bits of R, followed by n bits of G, B, and U (as appropriate). If the total number of bits is not a multiple of 8, it will be right-padded with zeroes.

Examples:

  • 4 bpc (bits per channel) and 4 colours would lead to a bit pattern of: RRRRGGGG BBBBUUUU.
  • 4 bpc and 3 colours would have a bit pattern of: RRRRGGGG BBBB0000
  • 12bps and 3 colours would have a bit pattern of: RRRRRRRR RRRRGGGG GGGGGGGG BBBBBBBB BBBB0000
  • 3bps and 3 colours would have a bit pattern of: RRRGGGBB B0000000

Co-ordinate

A co-ordinate consists of four two-bit values packed into a single byte, with the bit pattern: xxyywwhh. Co-ordinates of (0,0) are at the top-left of the module, and increase downwards and rightwards. Note that the ww and hh bits may be ignored.

Scroll spec

A scroll spec consists of two two-bit values and two one-bit values packed into a single byte, with the bit pattern: xxyy0w0h. The number of pixels to scroll along the X and Y axes is specified by xx and yy, and the direction is negative along the X/Y axis if w or h are set, respectively.

Commands

Commands start with a one-byte identifier, followed by zero or more data bytes. The number of data bytes is command-specific. The device should not output any data unless specified below.

Command Action Min version
Status/Diagnostic Commands
00 Reset 1.0
Resets the board to an initial state, with all pixels off. The board sends four bytes representing its hardware and firmware versions (2 bytes each), followed by 2 bytes for hardware details. This command also resets the board ID to 0xFFFF (i.e. unset).

The high nybble of the first hardware info byte is the number of different colours supported (0x1, 0x3, or 0x4) and the low nybble is whether sensors are supported (0x1 for yes). The high nybble of the second byete specifies the number of bits needed to specify LED brightness. If this is different for different colours, the firmware will handle scaling. The low nybble does the same for sensor resolution. Note that, for the time being, resolutions should be a power of 2 (0x1, 0x2, 0x4, 0x8).

01 Identify 1.0
Informs the board of its two-byte board ID for this session. Note that board IDs 0x0000 and 0xFFFF are reserved. The board will respond with 0x00 (success).
02 Ping 1.0
Checks connectivity with the board. The board will respond with 0x00 (success) followed by its two-byte board ID.
03 Query neighbours 1.2?
???
0E Display static test pattern 1.0
???
0F Display animated test pattern 1.0
???
Simple Display Commands
10 Clear floor 1.0
???
11 Write floor 1.0
???
18 Clear row 1.0
???
19 Write row 1.0
???
Complex Display Commands
50 Set pixel 1.1
???
51 Draw line 1.1
???
52 Draw hollow rectangle 1.1
???
53 Draw filled rectangle 1.1
???
54 Scroll floor 1.1
???
55 Scroll rectangle 1.1
???
5E Draw single-colour pattern 1.1
???
5F Draw pattern rect 1.1
???


Retrieved from ‘https://wiki.london.hackspace.org.uk/w/index.php?title=Project:USB_Disco_Dance_Floor/v1/firmware&oldid=13179’