bitfocus
[BUG] Mirabox N3 Stream Dock recognized as N4 / not working correctly — missing model & PID conflict (Windows build)
Make sure you're on the latest stable or beta build
- [x] I have tested this on the latest stable or beta release
Is this a bug in companion itself or a module?
- [x] I believe this to be a bug in companion and not a specific module
Is there an existing issue for this?
- [x] I have searched the existing issues
Describe the bug
The upstream TypeScript source defines the N3 model (293N3, PID 0x1003) including press, rotateLeft, and rotateRight inputs. However, the compiled Windows experimental build does not include this model.
After manually adding the N3 block to main.js and adjusting the detection logic (to account for the PID conflict described below), the device was recognized correctly and rotation events appeared in the logs. It was not possible to create an encoder control in the Companion GUI — there were no encoder placeholders and no “Rotary Encoder” buttons to bind actions.
Technically, I could assign those inputs to normal button actions in the main.js file, but that wouldn’t be correct, and I don’t have the experience to implement proper encoder handling myself. I just wanted to test my new device with Companion, noticed this issue, and thought it might help to report it — since not many users will own this hardware yet, it may be valuable early feedback for the development team.
My N3 device reports the same product ID as the N4 model listed in the source. While this might not affect every unit, it is likely that other users will encounter the same problem. Because both models can share the same PID, when the detection is set to one of them (for example, N3), all connected devices with that PID will be treated as N3 devices. If an N4 is then connected, it will also be recognized as an N3. This makes it impossible to operate both types of devices at once without.
Proposal: Add a per-device model override in the GUI (dropdown: Auto / N3 / N4 / 293V3 / HSV …) This would:
Allow users to manually select the correct model when detection is ambiguous.
Prevent PID collisions from breaking multi-device setups.
Also, adding encoder entries to the Mirabox CONTROLS array (type “encoder”, with properties like hasLed and ledRingSteps) would match the Stream Deck Plus behavior and enable proper encoder functionality in the GUI.
Steps To Reproduce
Install Windows experimental build ([email protected]+8573-develop).
Connect Mirabox Stream Dock N3.
Observe: device recognized as N4; “293N3” block missing in compiled JS.
Manually add the N3 definition.
Adjust detection logic if the product ID matches that of N4.
The device will now work and send rotation events, but encoder controls remain unavailable in the GUI. Buttons, Screen and others work.
Expected Behavior
The N3 model should be included in the Windows build.
The detection logic should correctly distinguish between N3 and N4 even if they share the same product ID.
The GUI should offer encoder placeholders (or “Rotary Encoder” buttons) to bind actions for rotateLeft and rotateRight inputs.
A manual model override option in the GUI would allow users to correctly select and operate both devices simultaneously.
Environment (please complete the following information)
- OS: Windows 11
- Browser:Chrome 141
- Companion Version: [email protected]+8573-develop (Windows experimental)
(Stable and Beta builds were tested before; both recognized the N3 as N4. I did not check their compiled files, assuming the experimental build would be the most recent. It’s possible that the N3 definition exists in those builds, but the detection logic is still incorrect.)
Device: Mirabox Stream Dock N3
References:
TypeScript source: companion/lib/Surface/USB/MiraboxStreamDock.ts
Compiled build: C:\Program Files\Companion\resources\main.js (around line 223241)
Additional context
The Mirabox driver contains a commented-out “layout” config section, suggesting future plans for user mapping. A model override option would align with that idea and solve the PID collision issue.
A manual override is the cleanest approach to ensure both N3 and N4 devices (sharing the same PID) can coexist in multi-device setups.
Many of my findings and suggestions were researched and discussed with ChatGPT. I’m not entirely sure whether every technical detail and conclusion is fully correct, but I hope this information is still useful for identifying and fixing the issues.
I really appreciate the work that goes into Companion and hope this feedback helps improve Mirabox support in future versions.
@asafbrukarz Tagging you here since you originally added Mirabox Stream Dock N3 support (commit #3686). This issue seems related — the N3 model appears to be missing in the Windows build and is detected as N4. Would be great if you could take a look when you have time. Thanks a lot!
However, the compiled Windows experimental build does not include this model.
The experimental builds are intended solely for testing new major/breaking features before they are finished and land in beta, so they often lag behind the beta builds. At present, there hasnt been any work on the experimental builds in 3+ weeks, and #3686 is newer than that which is why it doesnt work in those.
I'm using build v4.2.0+8547 on Mac. Can you confirm the PID reported by Windows for the N3? You're saying it's the same PID as the N4, which means that even before this change it would have been recognised as an N4. Is that correct?
Hi @Julusian @asafbrukarz — thanks for the quick replies, and sorry for my delayed follow-up.
Status update (Windows 11, beta v4.2.0+8547):
Confirmed: the N3 model definition is present in the current beta (thanks for pointing me away from experimental).
However, my Mirabox N3 enumerates as VID_5548, PID 0x1001 (4097) on Windows, so Companion still detects it as N4 by default.
Companion log (Windows 11, before manual Change):
25.10.25 12:36:45 Surface/USB/MiraboxStreamDock/\?\HID#VID_5548&PID_1001&MI_00#7&45dd2eb&0&0000#{4d1e55b2-f16f-11cf-88cb-001111000030}: Adding Mirabox Stream Dock N4 device: \?\HID#VID_5548&PID_1001&MI_00#7&45dd2eb&0&0000#{4d1e55b2-f16f-11cf-88cb-001111000030}
Verification / quick local test: To confirm this, I temporarily swapped the PID mapping in the compiled main.js so that 4097 (0x1001) → N3 and 4099 (0x1003) → N4. With that change, my device is recognized as N3 and rotation events are logged correctly. So there are definitely N3 units that report 0x1001 on Windows — meaning the original issue existed even before the recent N3 definition was added.
Excerpt from the compiled detection chain I modified for testing:
4101 === this.info.productId || 4102 === this.info.productId ? (this.model = zt.models["293V3"]) : 4099 === this.info.productId || 4103 === this.info.productId ? (this.model = zt.models["N4-1234"]) : 4097 === this.info.productId ? (this.model = zt.models["293N3"]) : 4116 === this.info.productId ? (this.model = zt.models["HSV 293S"]) : 26224 === this.info.productId ? ((this.model = zt.models["HSV 293S-2"]), (this.packetSize = 512)) : this.emit("remove")
Current behavior:
Buttons + LCD work normally.
rotateLeft / rotateRight events are received, but the GUI still doesn’t show encoder placeholders for Mirabox, so these inputs can’t be assigned to actions. This matches what I observed earlier — encoder mapping isn’t yet implemented for the Mirabox models.
Minor side note: in this beta, my Home Assistant server connection doesn’t work at the moment (it did in previous builds), but that’s fine — expected for a beta and probably unrelated.
Summary:
The N3 definition is now correctly included in beta (missing only from experimental).
The detection logic still fails for N3 units reporting PID 0x1001.
Rotary encoder controls are not exposed in the GUI yet, even though the events arrive.
A model-override option or improved detection for shared PIDs would fully resolve this.
Thanks again for following up on this — @asafbrukarz, this confirms the PID issue you suspected and that the encoder mapping still needs adjustment.
Something else to consider here, is that the model matching logic isnt considering the vendorId. So if two products have the same productId the matching logic will get them confused.
rotateLeft / rotateRight events are received, but the GUI still doesn’t show encoder placeholders for Mirabox, so these inputs can’t be assigned to actions.
Have you enabled the Rotary Actions toggle on the buttons that they map to?
Hi @Julusian @asafbrukarz,
First of all, I owe you an apology. I completely missed how to add rotary actions. I kept looking for a “create rotary button” option under Create Button, but the correct way is to create a normal button and then enable Rotary Actions. I searched for this for quite some time and somehow didn’t see it — now that I know where it is, it’s sooooooo obvious. Thanks for pointing me in the right direction.
I’ve now tested the actions, and everything works great after manually forcing the device to N3. The remaining issue is still the device recognition: my N3 gets detected as N4 unless I patch it. As you proposed, using the Vendor ID for disambiguation would help, but I’d also really appreciate a manual model override in the UI. That way, if auto-detection misjudges the device, I can explicitly set it (e.g., Auto / N3 / N4 / …) and use mixed setups reliably.
Thanks again!
Hi everyone,
I'm new here but am following your conversation with great interest, eventhogh I have no experience with coding etc.. I have experience with using Elgato Streamdecks for video and audio control (except Streamdeck+), but I'm looking to find a solution to use a hardware controller with AudioStröm's Live Professor as VST host to control plugins as part of my touring setup (Live Soundengineer). I recently stumbled across and bought the Redragon SS552 which should be identical to the MiraBox N4. Unfortunately they have their self branded version of the control software, in which I can select the SS552 (N4) device and install the Companion plugin. I can then assign buttons as companion buttons and assign actions within Companion, but when I switch to "knobs" I do no longer have the Companion plugin option on the items list on the right of the Redragon software. I can only drag and drop their premade actions on one of the rotaries. Is this different to the MiraBox Software? And if so, do you know, if there is a way to implement the Redragon device into MiraBox's GUI, as the hardware should be identical, only an OEM version. Also does anyone here have experience or done what I plan already?
Thanx in advance,
Best,
AAA
Hi @bfnjkmd979-sudo, welcome! You’re a bit off-topic here — this thread is about a detection issue with Mirabox devices in Bitfocus Companion, not about the manufacturer’s own software. But no worries, let’s clear things up real quick:
The software that came with your Redragon SS552 is most likely called VSD (can you confirm if that’s the name?). That app isn’t the real Companion — it’s an OEM version with a Companion plugin built into it. You don’t need that, and it actually prevents the real Companion from communicating with the device.
➡️ Please uninstall or fully close the VSD/Redragon/Mirabox software (make sure it’s not running in the Task Manager). ➡️ Then install Bitfocus Companion directly — preferably the latest beta, since it definitely includes Mirabox N4 support (the stable might work too). ➡️ Plug in your controller and check under Surfaces how it’s recognized. If it doesn’t show up correctly, please post the Vendor ID and Product ID, and we can compare if it’s affected by the same PID conflict discussed above.
For the rotary knobs: in Companion they appear as part of the virtual button grid (the ones under the small displays). Just create a normal button, then enable Rotary Actions for it — that’s where you can assign functions for turning left/right.
Once you’ve tried that, let us know:
Whether the device connects correctly
And if it shows up under the right model name in Surfaces
That’ll help us see if it’s working out of the box for the Redragon model too.
— Allcrafter1
Hi Allcrafter1,
Thank you very much for your extensive response, I can already see I've come to the right place ;-).
So to clarify, I have found 3 different Software Files
Mirabox and 2 Versions of Red Dragon.
Streamdock Installer Mac Stream Controller.app.sig3.10.194.0717 and Redragon Stream Station.app.sig.pkg , installed 1,17 GB, uses the red Redragon logo as thumbnail (this one works and will also show the button and rotary layout as on the controller. I could also select SS-551, the one with the additional 3 buttons and only one big rotary knob.
They all have different opening animations and the Redragon Stream Station one once open, only offers the Stream Dock 293S (the one with 3 x 5 buttons and the infoabar on the side.
Eventhough is starts up, it doesn't detect any devices. I can go to this page... https://space.key123.vip/home?token= which features all kinds of plugins, themes, button design etc.
Back to your questions:
Where do I find if it's the VSD software?
Also on the Mirabox page it says it's compatible with all kinds go controllers incl. N4 and N4 pro, but the picture only shows the 293S. Strangely, when I install this version, in my programs it's listed as Redragon Stream Dock with a square symbol that looks like a Rubics cube.
My Companion version is v4.1.4+8492-stable-4cb4314544, it's running on an Intel MacBook Air 2019 via USB C.
Under surfaces and even after Rescan USB, the SS552 doesn't show, nor the N4...
Where would I find the Vendor ID and Product ID?
In Settings Enable direct connection to Streamdecks When disabled support for the Elgato software Plugin will be enabled (Requires Companion restart)
and
Enable connected X-keys (Requires Companion restart)
Are both off, as suggested in a Reddit Thread. When I have the correct Version of Redragon installed, Companion and the SS552 will talk to each other, and I can configure buttons in Companion, and if I assign the "ithin the Redragon software on the bottom I get "Connected to Companion" in green and if I adjust row and column correctly, it will show me the correct image of the Companion button and the yellow bar on top when th button is pushed. This works in all directions including clicking on test within Companion.
I did everything like you said, but unfortunately no results.
I think I just found something, If I assign an Operation trigger from the Knob tab and double click on the symbol in the scrollbar, I can pull the Companion button item on the rotary separate for left turn, right , push function and right turn individually and then assign an action in Companion...
What are your thoughts?
Thank you again for looking into this for me,
Best,
AAA
Hi @bfnjkmd979-sudo, I think there’s still a bit of confusion here — and I’ll try to clarify it as clearly as possible:
This thread is not about using the manufacturer’s software (Mirabox / Redragon / VSD). Those apps — regardless of which version you have — block Companion from accessing the device directly. Even if they show “Connected to Companion” or have a Companion plugin, that’s just a bridge inside their software, not the real Companion integration. Something that the manufacturer weirdly included.
You’ll need to COMPELETLY quit or uninstall any of those apps first — on macOS that means using Cmd + Q or closing them from the Activity Monitor. They must not be running in the background at all.
Then, install the real Bitfocus Companion, preferably the latest beta version. Your version v4.1.4+8492-stable is very likely too old — that’s probably why the SS552 (N4 clone) doesn’t show up under Surfaces. The current beta contains the Mirabox definitions and should detect it correctly.
Once you’ve done that:
-
Plug in the device.
-
Check under Surfaces what it’s recognized as.
-
If nothing appears, please post the Vendor ID and Product ID (you can find them under About This Mac → System Report → USB). At least that's what ChatGPT told me where you would find it. Otherwise just Google it or ask ChatGPT.
The Redragon / Mirabox / VSD software is not needed at all for Companion. It will only interfere. This thread itself focuses on a PID detection issue inside Companion, not the manufacturer’s control software.
Hope that clears things up — uninstall the OEM apps, install the latest Companion beta, and it should start working properly.
— Allcrafter1)
First of all, I owe you an apology. I completely missed how to add rotary actions. I kept looking for a “create rotary button” option under Create Button, but the correct way is to create a normal button and then enable Rotary Actions. I searched for this for quite some time and somehow didn’t see it — now that I know where it is, it’s sooooooo obvious. Thanks for pointing me in the right direction.
I’ve now tested the actions, and everything works great after manually forcing the device to N3. The remaining issue is still the device recognition: my N3 gets detected as N4 unless I patch it. As you proposed, using the Vendor ID for disambiguation would help, but I’d also really appreciate a manual model override in the UI. That way, if auto-detection misjudges the device, I can explicitly set it (e.g., Auto / N3 / N4 / …) and use mixed setups reliably.
Thanks again!
While it's possible to check for the 0x1003 PID, AND the VID_5548&PID_1001 combo, it's hard to know how other N3 devices are reporting their VID/PID. @Julusian what do you think? Is there a risk of adding that specific VID/PID combo?
Is there a risk of adding that specific VID/PID combo?
There is, but I think it is worthwhile instead of forcing the user to manually correct this.
Thinking more on this, having a manual option will add quite a lot of complexity to handle;
- There isnt support for a surface changing its size, so every mirabox would need to present as the max dimensions
- Probably going to be some issues with it skipping the first draw after changing that setting
- In the soon future, we will require each surface to provide a layout manifest, defining the buttons/encoders with their placement and the image size/format needed. So this option will need to either be able to tell companion to reload that (which becomes very complex when considering this should be possible in satellite too), or to reload the whole mirabox handler.
Would it be worth considering the model description in the event of ambiguity, or do they not vary between the N3/N4 in this case?
@peternewman I don't know. I only have the N3. But we never can be sure it's the same for all models. Also the N4 already has two product IDs configured. Maybe @bfnjkmd979-sudo can provide one combo for the N4. But it will be hard getting all the info from users.
Mirabox is using two IDs, one for the chinese model and one for the english model. I can imagine that it is the same for N3. N4 chinese is VID 6602 PID 1001 and english is VID 6603 PID 1007 293V3 chinese is VID 6603 PID 1005 and english is VID 6603 PID 1006 Your copy of the N3 seems to be VID 5548, PID 1001.
The code does not check for combinations of VID and PID but first checks for any of the vendor IDs and then for the product ID. This hasn't been a topic while PIDs were unique but with addition of two devices with the same VID this clearly is a bug.
Hey all — I spent some more time thinking about this and also talked it through with ChatGPT. I honestly can’t claim that I fully understand internal architecture details of Companion, but I think I now better see the constraints you’re worried about (dynamic resizing, layouts, upcoming manifest handling, Satellite sync, etc.).
Based on that, I had an idea that might be a possible middle ground:
Instead of allowing a live model switch on an already-initialized surface, what if the model override happens before the final surface layout is created at all?
Rough flow:
When a Mirabox device with ambiguous VID/PID is detected, Companion creates a temporary “unfinalised” Mirabox surface.
In the surface config UI, the user is asked to select the concrete model (Auto / N3 / N4 / 293V3 / HSV…).
Once confirmed, Companion creates the final surface layout based on that selection.
The choice is stored persistently per physical device (serial/path), so it survives restarts.
This way the override does not need to resize or remap an already-active surface, since the decision is made before layout initialisation. In the typical case it’s a one-time choice per device.
For changing the model later: personally, I’d be totally fine if this triggers a full surface reset with a warning (“changing model will reset this surface”). That still seems much safer and simpler than trying to dynamically morph existing layouts.
I get that the first step should probably still be fixing the current VID+PID auto-detection for known devices — I fully support that as the immediate bugfix, and I’m happy to help testing it on real hardware (N3-style device: VID 5548 / PID 1001 on Windows 11).
Long-term though, because manufacturers like Mirabox reuse IDs and different physical devices can share the same VID/PID, some form of per-device persisted override feels unavoidable if mixed-device setups should work reliably — especially once Satellite support comes into play.
Thanks again for all the work you’re putting into this — and sorry if any of my assumptions are off; this is very much from the perspective of a power user trying to bridge the real-world hardware chaos with Companion’s internal model.
While that would work, the current config flow doesnt support this; it only gets provided to the surface once it has been fully initialised. So to support this would require some engineering.
And I am not yet entirely convinced that there are duplicate vid+pid pairs, or if it is duplicate pids that we should be separating out with vids.
So before we jump to implementing to bad UX flow (which from experience, users will put up with rather than help us refine the automated flow), I want to confirm that this is actually the only way to solve this.
From Dorian's comment, tracing through the history and a bit of guesswork I come up with:
- 293V3 - vid 0x6603, pid 0x1005 & 0x1006
- HSV 293S - vid 0x6602 & 0x6603, pid 0x1014
- HSV 293S (2) - vid 0x5548 & pid 0x6670
- HSV 293S (3) - vid 0x1500 & pid 0x3003
- N3 - vid 0x6602 & 0x6603, pid 0x1003
- N4 (1234) - vid 0x6602 pid 0x1001 & vid 0x6603 pid 0x1007
- N4 (1245) - unused
Of course, there could be some hardware matching by luck. Your N3 (vid 0x5548, pid 0x1001) doesnt match any of those,
Something else to note, is that I am reworking how surfaces work for 4.3, and that will require us to be matching exact vid+pid pairs. So in 4.3, this matching will need to be reworked anyway.
Then the question becomes what to do about this for 4.2; considering that it will be released within the next month and it would be good to not break things for people.
The change with least risk would be to do an explicit matching of only your vid 0x5548 pid 0x1001 and make that be an N3, and leave the rest of the ids to be firmed up in 4.3. If that breaks for anyone, then we will know for certain that we need to handle multiple models under a single vid+pid and it can then be decided on how best to handle that.
The change with least risk would be to do an explicit matching of only your vid 0x5548 pid 0x1001 and make that be an N3, and leave the rest of the ids to be firmed up in 4.3. If that breaks for anyone, then we will know for certain that we need to handle multiple models under a single vid+pid and it can then be decided on how best to handle that.
I decided to just do this now, it will be in the next beta