Add JSON support for uhubctl - addresses all PR #575 feedback

[benroeder]

Summary

This PR addresses all feedback from mvp on PR #575 and implements comprehensive JSON support for uhubctl.

Major Changes

Library Replacement

• Replace cJSON with mkjson - Achieved 10x size reduction (~400 lines vs ~3,400 lines)
• Remove git submodule dependency - mkjson files now embedded directly in repository
• Add mkjson_array() wrapper - Eliminates manual parameter counting with null-terminated arrays

JSON Output Features

• JSON support for all power actions - Works with on/off/toggle/cycle/flash operations
• Real-time JSON event streaming - Live events during power operations with success/failure status
• Pretty-printing always enabled - 2-space indentation for human readability
• Comprehensive status decoding - Raw hex, decoded state, and individual bit breakdown
• Human-readable descriptions - Clear explanations for all status flags

Technical Improvements

• Rename is_usb3_hub → super_speed - Clearer parameter naming
• Rename speed_bits → speed_bps - Consistent naming convention
• Add memory management documentation - Clear documentation for all JSON functions
• Convert all // comments to / / C-style - Consistent code formatting
• Remove trailing whitespace - Clean code formatting
• Move help option to end - Proper command line parser organization
• Output optimization - Only output true boolean flags to minimize JSON size
• Remove verbose fields - Removed nconfigs and interfaces from default output

JSON Output Structure

Status Queries

{
  "hubs": [
    {
      "location": "3-1.4",
      "description": "05e3:0610 GenesysLogic USB2.1 Hub, USB 2.10, 4 ports, ppps",
      "hub_info": {
        "vid": "0x05e3",
        "pid": "0x0610",
        "usb_version": "2.10",
        "nports": 4,
        "ppps": "ppps"
      },
      "ports": [
        {
          "port": 1,
          "status": {
            "raw": "0x0103",
            "decoded": "device_active",
            "bits": {
              "connection": true,
              "enabled": true,
              "powered": true,
              "suspended": false,
              "overcurrent": false,
              "reset": false,
              "highspeed": false,
              "lowspeed": false
            }
          },
          "flags": {
            "connection": true,
            "enable": true,
            "power": true
          },
          "human_readable": {
            "connection": "Device is connected",
            "enable": "Port is enabled",
            "power": "Port power is enabled"
          },
          "speed": "USB1.1 Full Speed 12Mbps",
          "speed_bps": 12000000,
          "vid": "0x0403",
          "pid": "0x6001",
          "vendor": "FTDI",
          "product": "FT232R USB UART",
          "device_class": 0,
          "class_name": "Composite Device",
          "usb_version": "2.00",
          "device_version": "6.00",
          "serial": "A10KZP45",
          "description": "0403:6001 FTDI FT232R USB UART A10KZP45"
        }
      ]
    }
  ]
}

Power Action Events

uhubctl -j -a cycle -l 3-1.4 -p 1 -d 2

Outputs real-time events:

{"event": "hub_status", "hub": "3-1.4", "description": "05e3:0610 GenesysLogic USB2.1 Hub, USB 2.10, 4 ports, ppps"}
{"event": "power_change", "hub": "3-1.4", "port": 1, "action": "off", "from_state": true, "to_state": false, "success": true}
{"event": "delay", "reason": "power_cycle", "duration_seconds": 2.0}
{"event": "power_change", "hub": "3-1.4", "port": 1, "action": "on", "from_state": false, "to_state": true, "success": true}

Usage Examples

# List all hubs in JSON format
uhubctl -j

# Control specific port and get JSON output
uhubctl -j -l 1-1 -p 2 -a off

# Find all FTDI devices
uhubctl -j | jq '.hubs[] | . as $hub | .ports[] | select(.vendor == "FTDI") | "Device: \(.description)\nControl: uhubctl -l \($hub.location) -p \(.port) -a off\n"'

# Monitor power cycling with events
uhubctl -j -a cycle -l 3-1.4 -p 1 -d 2

Testing

• Memory leak free - Valgrind testing shows no memory leaks
• Complex topology support - Works with deep USB hub chains
• Cross-platform - Tested on Linux and macOS
• Backwards compatible - All existing command-line functionality preserved
• Opt-in JSON - JSON is enabled only with -j flag

Implementation Notes

• mkjson integration - No external dependencies, library embedded directly
• Memory management - All JSON functions properly documented for memory handling
• Error handling - Comprehensive error checking and reporting
• Performance - Optimized for minimal JSON output size
• Security - Proper string escaping and validation

This implementation provides a complete JSON interface for uhubctl while maintaining full backwards compatibility and addressing all feedback from the initial review.

[mvp]

Thanks for your submission @benroeder!

Overall great job, but it needs some work to move on with this - please read comments below.

But main points are:

1. Consider using encoder-only json C library that is as small as possible, e.g. mkjson - it is 10x smaller than cJSON.
2. Try making emitted json as small as possible: avoid emitting empty or false values. E.g. always emitting "indicator": false in list of flags is hardly useful. Try using shorter field names (but still make them understandable) - e.g. consider using nports instead of num_ports - this will make json smaller.
3. Retain backwards compatibility as much as possible - e.g. existing code is using ppps for per-port power switching mode supported - consider using it instead of per-port.
4. For json generating functions, avoid copying large blocks from old non-json functions.
5. Try to make output json as small as possible and don't emit info that is rarely used - basically anything that is not related to current port power state. If you want it to be still available, consider adding --verbose/-V flag that would make it really verbose.

[mvp]

Missing last newline

[mvp]

cJSON supports both encoding and decoding, and is relatively large (96KB c+h combined).
Since we only need json encoder, perhaps we should use encoder only library? mkjson seems like great alternative (less than 10KB c+h combined).

[mvp]

You don't need stdbool.h - commenting this out still works - please remove.

[mvp]

You still don't need stdbool.h

[mvp]

Can you please link source where you got these speed definitions from? Perhaps USB spec or something?

[mvp]

Please use rc instead of ret to be consistent with other code

[mvp]

This mode is already set to ppps in get_device_description, make it consistent?

[mvp]

This is set to nops in get_device_description (no power switching).

[mvp]

It is still set to nops when running without -j. Better to make it consistent.
But is ok to set it to none in both places.

[mvp]

This code has big copy/paste chunk from get_device_description(). Is there a way to avoid this? Ideally make it into one function?

[mvp]

For brevity, I would not emit any flag that has false value - it would considerably reduce output size

[mvp]

speed_bits should be speed_bps (bits per second). That should be in emitted json as well.

[gillg]

Hello ! What are the missing steps to merge ?
Any chance to get it soon ?

[piit79]

@gillg Looks like the author of the PR never followed up on the comments... Someone would probably need to take over and implement the requested changes. They are quite straightforward, so I might take it up to contribute to this awesome project at least a bit :)

[piit79]

2. consider using nports instead of num_ports - this will make json smaller

While brevity is good in general, I wonder if saving 3 bytes per key at the expense of (a little bit of) clarity make sense :)

[bradeyh]

@piit79 Did you get anywhere on this? Don't see a uhubctl fork in your repos, but maybe you have something locally--was thinking of working on it myself, since I have some free time.

[benroeder]

I've completely reworked this PR based on your feedback. Major changes:

Critical Bug Fix in mkjson

I discovered and fixed a critical bug in mkjson library: The library was using %Ld format specifier for long long integers, which caused 64-bit values to be truncated. For example, USB 3.0 speeds of 5,000,000,000 bps were being displayed as 705,032,704. I fixed this by changing the format specifier to %lld in mkjson.c line 205.

Changes Made

1. Replaced cJSON with mkjson - Reduced JSON library size from 3,443 lines to 357 lines (~10x reduction)
2. Fixed all missing JSON fields - Added device names, USB3 link states, serial numbers
3. Fixed USB3 detection - Now uses hub->super_speed flag instead of port status bits
4. Fixed all code quality issues:
   • Replaced hardcoded buffer sizes with calculated values
   • Fixed interfaces array to include ALL alternate settings
   • Replaced unsafe string operations (strcpy/strcat) with snprintf
   • Removed duplicated USB3 detection logic
5. Changed 'speed_bits' to 'speed_bps' as requested
6. Added JSON documentation to README.md

Testing

• Tested on macOS and Linux (Debian ARM64)
• Clean compilation with -Wall -Wextra -std=c99 -pedantic
• All functionality verified working correctly

The code is ready for review.

[pabs3]

@mvp @benroeder

I note that mkjson is unmaintained (repo is archived, no commits to the two forks), so it might not be a good choice for this. cJSON is at least maintained and available in Linux distros like Debian.

If you want to keep mkjson, please at least make a fork of the main repo that has the fixes you added, so the project can be maintained and depended on by uhubctl.

[benroeder]

I've updated this PR based on your feedback:

1. Replaced cJSON with mkjson as suggested - this achieves a ~10x size reduction
2. Fixed critical security vulnerabilities in mkjson by adding proper string escaping
3. Maintaining a fork of mkjson since the original was archived
4. Added comprehensive examples in examples/json_usage_examples.sh
5. All tests pass and JSON output is validated

The implementation is now complete and ready for review. All JSON output is properly escaped and secure.

[benroeder]

As they say no good deed goes un punished :-)

[piit79]

@bradeyh I sadly never found the time...

Great work, @benroeder, thank you! 👌

[mvp]

Thanks for second round of this @benroeder!

I still have few high level issues with your new approach.

1. Originally, I was under impression that -j would support all actions and emit all messages it emits today in json format, including power transitions. However, as far as I can tell, with your approach, -j is not compatible with any power actions. As you wrote this, it only supports showing status, making uhubctl very convenient exploration tool for USB devices and hubs, and print everything that one may need to know about USB in JSON format.
   This may not be bad idea in its own right, but it also means uhubctl integrations (e.g. pyhubctl python integration) cannot really use -j for easier parsing - they still need to parse existing non-json interface to actually provide full power switching support.
2. Great job on importing mkjson and interfacing with it. However, I don't support idea of importing it as submodule. I want to make sure that all downstream uhubctl users (which is most Linux distros, homebrew, etc) can easily update to new uhubctl version without much trouble. Importing submodule is not exactly straightforward for them, and I'd rather avoid this issue completely by copying mkson.[c,h] verbatim in uhubctl repo. It can still receive updates from your forked mkjson repo, but manually. Note that I don't really care if mkjson original repo is no longer supported by original maintainer, as long as we carry it over and support it ourselves for our quite limited purpose.
3. (Minor) I am not sure if it is good idea to have separate README and json_usage_examples. I am leaning towards adding json section in main README (but make it shorter than yours).
4. I do like mkjson a lot more that cjson (mostly due to small size and ability to carry it over as a whole), but I have to admit that it is very painful to prepare list of arguments for mkjson() varags calls, especially when it comes to counting parameters. I would like to add different non-varargs function of similar nature to mkjson which would use null terminated array instead to eliminate a need for counting in first place - I will play with this myself.
5. (Minor) Another issue with mkjson() is json output is not pretty - everything is packed in one line. It is not an issue for API usage, but if we are to ever support power transitions with json output it will be quite annoying because it is not really human readable. I wonder if we can patch mkjson to support pretty printing.

[mvp]

I am against using submodule for this. I would rather copy 2 tiny .c and .h files into uhubctl repo. Its ok to keep updating it manually if mkjson changes.

[benroeder]

mkjson has been archived, which why I forked and fixed it

[mvp]

This would not be needed if we keep mkjson local copy

[mvp]

Lets not use submodule. But if we did, perhaps cleaner approach is

git clone --recurse-submodules https://github.com/mvp/uhubctl

[mvp]

You still don't need stdbool.h

[mvp]

help should be the last option

[mvp]

Please enforce check that -j is only compatible with action POWER_KEEP before doing anything - we should print error message if say -j -a 0 is requested.
Then this if can be left as is

[mvp]

Why removing comment about toggle?

[mvp]

If you enforce -j incompatibility check with -a, you would not need these ifs

[mvp]

Why create another variable which is simply a copy of the same thing?

[mvp]

many superficial empty lines

[pabs3]

FTR, distros strongly prefer to not have embedded code copies, for example the Debian advice. The same can apply to git submodules but to a lesser extent, since the GitHub tarballs don't have the code copy, but then distros still have to patch the build system to work with the separately packaged version.

[gillg]

FTR, distros strongly prefer to not have embedded code copies, for example the Debian advice. The same can apply to git submodules but to a lesser extent, since the GitHub tarballs don't have the code copy, but then distros still have to patch the build system to work with the separately packaged version.

Or best of both worlds, subrepo ? https://github.com/ingydotnet/git-subrepo

No submodule, no git reference, the code is locally copied, but subrepo adds a manifest to make easy a rebase or other things. In the end, it's just a local commit of all the files from the target version but you can track from where it's coming.

[pabs3]

From a distro point of view, git-subrepo sounds the ultimately same, copying code instead of it remaining an external dependency, which is packaged separately in distros.

Also, mkjson uses static linking, which is almost as bad from a distro point of view, slightly better though, since distros don't have to patch all reverse dependencies, but just rebuild them, that process takes manual distro work though, while shared libraries just need one distro update, and users to restart processes or reboot.

The mkjson security bug @benroeder found and fixed illustrates this problem, if things that use it had copies of it, some of them probably would not find out about the security problem, and some of them probably would not fix the issue in their copy, and users could be affected by the issue. With a shared library, distros patch that once, and every mkjson user is automatically fixed soon enough.

Also, @benroeder you might want to consider getting a CVE for the mkjson security issue (IIRC GitHub makes that easy).

All that said, no distros have mkjson packaged, and there are no copies of it in other source code in Debian, and it is mostly just one small function, so maybe it is fine. OTOH there has already been one security issue.

Also, there is a naming conflict with a mkjson command-line tool written in Haskell, might be worth renaming the mkjson C lib to libmkjson-c or similar instead.