DOCSEARCHbyAlgolia
Submit Docs

dysentery

repository·main·Indexed 42 days ago

https://github.com/deep-symmetry/dysentery

A tool for exploring and analyzing packets sent within a Pioneer Pro DJ Link network, primarily used for research into undocumented protocols used by DJ hardware. It identifies connected devices like CDJ-2000nexus and provides network details required to create virtual CDJ devices. Includes detailed packet analysis and captures for CDJ-2000NXS firmware 1.44, covering NFS implementation, dbserver and menu protocols, and media status behavior.

Tokens
20.4K
Snippets
39
Records
108
Agent score
54%

What's inside dysentery

  1. Interpret CDJ-2000NXS hardware captures

    main

    This directory contains packet captures from a rig of two CDJ-2000nexus players on firmware 1.44. These captures are used to validate a Python implementation of the protocol.

    Hardware Rig Details

    • Model: CDJ-2000nexus
    • Firmware: 1.44
    • Network: Self-assigned 169.254/16 (no DHCP).
    • Identification: Both decks report an identical 20-byte name (CDJ-2000nexus). Do not use the name field to identify a device; use the MAC address instead.

    Capture Provenance

    Every byte in these captures was recorded directly from the wire between real Pioneer hardware. No data was generated, replayed, or synthesized. Each session directory contains a NOTES.md file acting as a lab record (hardware state, user actions, and observations) and a cmd.txt file containing the exact tcpdump command used to generate the capture.

  2. Identify DJ Link UDP packet structure

    main

    DJ Link protocol packets sent over UDP follow a specific structure. All packets begin with a fixed 10-byte magic sequence. The 11th byte (the byte immediately following the magic sequence) identifies the packet kind when combined with the destination port.

    Magic Sequence (Hex): 51 73 70 74 31 57 6d 4a 4f 4c

    51 73 70 74 31 57 6d 4a 4f 4c

  3. Understand Stagehand Device Identity (MAC and Device Numbers)

    main

    Stagehand uses a dual-identity model that can complicate network monitoring:

    1. Dual MAC Addresses:

      • Protocol-layer MAC: Embedded inside 0x02 and 0x06 payloads. This is a stable AlphaTheta-OUI (c8:3d:fc:**:**:) used by the A9 for unicast pairing.
      • Link-layer MAC: The actual Ethernet/802.11 MAC visible via ARP (e.g., 5a:2d:07:**:**:**). This is the iOS Wi-Fi privacy MAC.
      • Note: When performing MITM (Man-in-the-Middle) attacks, use the link-layer MAC for the target list, but use the protocol MAC for payload comparisons.

    2. Device Numbers:

      • While Stagehand claims 0x3a (58) in its handshake, it operates with a random runtime number drawn from the high range (0x80–0xff) on each launch. This number is found at byte 36 of the 0x06 keep-alive packet.

  4. Understand the impact of capture tap selection

    main

    When analyzing these captures, you must identify the Tap used, as it significantly affects what data is visible. Using the wrong tap can lead to false conclusions about protocol silence.

    BSD Bridge Tap (bridge1)

    • Behavior: Floods broadcast frames to the BPF tap, making keep-alives, hellos, and claim packets visible.
    • Limitation: Unicast traffic is forwarded member-to-member and never reaches the bridge tap.
    • Warning: If you see an absence of UDP 50002 (Status), media query/responses, or dbserver TCP traffic in a bridge1 capture, treat it as unmeasured, not as evidence that the devices were silent.

    Member Interface Tap (pktap,en12,en9)

    • Behavior: Records both member interfaces simultaneously, allowing visibility into unicast traffic.
    • Limitation: Because it records both interfaces, every broadcast frame is written twice (a fraction of a millisecond apart).
    • Warning: Naively counting broadcast packets (like keep-alives or claim packets on UDP 50000) will result in double the actual count and an apparent cadence that is half the real speed.

    Verification Rule of Thumb

    To verify if a tap is working correctly, check for unicast traffic. For example, a LINK browse must produce TCP traffic on ports 12523 and 1051. If this traffic is missing, the tap is lying.

  5. Hardware limitations for track loading (XDJ-XZ and CDJ-3000)

    main

    Not all players support remote track loading identically:

    • XDJ-XZ: Can load tracks from a rekordbox collection when instructed by rekordbox. However, it cannot be remotely instructed to load tracks from its own USBs or from other players. Remote loading for XDJ-XZ requires specific packet variations (byte 20 as 01 and byte 4b as 32), but even then, it only works if the track is from the rekordbox collection.
    • CDJ-3000: If you attempt to load an unanalyzed track (from the Folders menu), the player will ignore the track type byte and instead attempt to load a rekordbox track with the same ID.

  6. Understand Field Types in the Database Protocol

    main

    All messages in the protocol consist of type-tagged fields. The first byte of a field identifies its type:

    TypeDescription
    0f1-byte fixed-length integer
    102-byte fixed-length integer
    114-byte fixed-length integer
    14Variable-length binary blob (preceded by a 4-byte big-endian length)
    26Variable-length UTF-16 big-endian string (preceded by a 4-byte big-endian length, ends with 0000 NUL)

  7. Parse Extended Cue/Loop Point Entries

    main

    Extended cue entries are variable-length blobs found in track metadata. To parse them, you must iterate through entries using the length field (the first 4 bytes) to find the start of the next entry.

    Key Fields:

    • length (bytes 0-3): Total length of the entry (little-endian). Use this to skip to the next entry.
    • H (byte 4): Hot cue indicator. 00 for ordinary cue points; 01 through 08 for Hot Cues A-H.
    • Fl (byte 6): Type indicator. 01 for memory point, 02 for loop. If both H and Fl are 00, ignore the entry.
    • cue (bytes 0x0c-0x0f): 4-byte little-endian integer representing the cue position in $1/150$ second units.
    • loop (bytes 0x10-0x13): 4-byte little-endian integer representing the loop end in $1/150$ second units.
    • cid (byte 0x22): Color ID for ordinary memory points/loops (maps to rekordbox color table).
    • len_c (byte 0x48): 2-byte little-endian integer for the length of the UTF-16 comment string.
    • comment: UTF-16 encoded string following len_c.
    • Hot Cue Colors: Located 4 bytes after the end of the comment. Consists of a color code (c) and RGB values (r, g, b).

    Warning: Some entries may be incomplete (ending before the comment or hot cue color). Code must handle partial entries by treating missing fields as empty/null.

  8. Understand the `_r:m:s:t_` argument structure

    main

    Every menu request requires a four-byte first argument referred to as _r:m:s:t_. Each byte represents a specific component of the request:

    1. Byte 1 (Requester _r_): The device number D of the player making the request.
    2. Byte 2 (Menu Location _m_): Identifies which menu location on the player will display the result.
      • Example: 3 for metadata preview of a selected track.
      • Example: 8 for non-text data like waveforms, album art, or beat grids.
    3. Byte 3 (Media Slot _s_): The media slot S~r~ being requested (matches CDJ status packet values).
    4. Byte 4 (Media Type _t_): The media type T~r~ being asked about (matches CDJ status packet values).

  9. Understand the device network presence rule

    main

    Devices in this system use a single latch mechanism to determine if they were the first device on a network during their boot sequence. This latch is set once at boot and never re-evaluated. This state drives two specific observable behaviors in the device's communication protocol:

    1. Stage-3 claim frequency: A device will repeat its stage-3 claim 3x if it was the first on the network, but only 1x if it is joining an existing network.
    2. Keep-alive byte (0x25): The value of the keep-alive byte 0x25 indicates network presence:
      • 0x02 if the device was the first on the network.
      • 0x01 if the device is joining an existing network.

    These behaviors are implemented in VirtualCdj, and the system's announcer is capable of reproducing these handshake variants byte-for-byte.

  10. CDJ-2000NXS dbserver and Menu Protocol

    main

    The dbserver protocol handles menu navigation and track browsing. Key technical details include:

    • Multiplexing: A single TCP connection (typically port 1051) multiplexes both SD and USB slots, distinguished by a descriptor byte.
    • Connection Setup: Handshake involves a port query on TCP 12523.
    • Navigation: Drill-down requests use a grid format: 0x1000 | depth << 8 | category.
    • Sorting: Sorting selects the item's second column.
    • Menu Surface: Supports GENRE, ARTIST, ALBUM, LABEL, BITRATE, HISTORY, KEY, SEARCH (text), and twelve sort modes (including Camelot key ordering).

  11. How the Tempo Master handoff protocol works

    main

    When a device requests to become the tempo master while another device is already acting as master, a coordinated handoff occurs via the following steps:

    1. Takeover Request: The requesting device sends a takeover request packet (Header 0x26) to port 50001 of the current tempo master. The value D in this packet is the player number of the device wanting to become master.
    2. Handoff Agreement: The current master responds by sending a takeover response packet (Header 0x27) to port 50001 of the requesting device. The value D in this packet is the current master's own device number.
    3. Announcement: The outgoing master continues to report itself as master in status packets, but sets the M~h~ field to the device number of the incoming master to announce the transition.
    4. Role Assertion: Once the incoming master sees its own device number in the outgoing master's M~h~ field, it begins reporting itself as the master in its own status packets.
    5. Completion: Once the outgoing master sees the new master asserting the role, it stops reporting itself as master, resets M~h~ to ff, and increments its Sync~n~ value.

  12. Understand the Packet Window visualization

    main

    The Dysentery GUI provides a visual representation of network packets to aid in protocol analysis:

    • Blue background: Indicates a byte or timestamp has changed recently; the color gradually fades back to black.
    • Green background: The byte has a value that is currently expected/known.
    • Red background: The byte has an unexpected value (potential error or new discovery).
    • White background: The byte's meaning is currently unknown (a 'puzzle').
    • Text rendering: Bytes expected to contain device names or firmware versions are rendered as readable text instead of hex.
    • Interpretations: Beneath the raw bytes, Dysentery provides an interpretation of the packet meaning based on current research.