Jump to content
Corsair Community

Developers: The Corsair Link USB protocol!


CFSworks

Recommended Posts

Hey all!

 

I'm on Linux, not Windows, so the Corsair Link software is not usable for me. Instead, my goal is to write a kernelspace driver to integrate the Corsair Link sensors and fan control into the Linux hwmon subsystem. This would make Corsair Link devices show up in lm_sensors. :biggrin:

 

To that end, I've started prodding around with the USB protocol to see how the software interacts with the hardware. I'm using a Windows XP VM with the Corsair Link 2 software, and USB pass-through on my H100i. The H100i is pretty much the only device at my disposal, so I may end up making some generalizations here. :)

 

It should be noted that this is being done purely through observation. No reverse engineering of the software is being done and no licenses are being violated.

 

 

Corsair Link protocol overview (unverified)

 

The USB device is actually an HID report device. This simplifies things, because the HID protocol is concerned purely with sending and receiving fixed-length buffers. It also means no specialized drivers are required. On Windows, you can just use the HidD_SetFeature/HidD_GetFeature calls. On Linux, open /dev/hidraw* and perform ordinary reads and writes.

 

In this case, both the input and output are zero-padded to 64 bytes even.

 

The device contains a number of registers, identified by a single byte, that can be read from and written to.

 

Output (sending commands from host->USB):

 

The HID reports are formatted with a one-byte length tag (indicating how many significant bytes the message contains) followed by that many bytes, then zero-padded to a length of 64.

For example, if I wanted to send a 5-byte message to my device, I would send:

05 XX XX XX XX XX 00 00 00 00 00 00 00 [...64 bytes]

 

The message payload contains one or more commands. A command consists of the command ID (one byte, used to identify the command when the device responds), the command opcode (one byte), and any arguments that the command expects.

 

Here are the commands that I have found so far:

06 AA BB - Write BB into one-byte register AA

07 AA - Read from one-byte register AA

08 AA BB CC - Write BB CC into two-byte register AA

09 AA - Read from two-byte register AA

0A AA 03 00 11 22 - Write 3-byte sequence (00 11 22) into 3-byte register AA

0B AA 03 - Read from 3-byte register AA

 

Input (receiving replies from USB):

Like with the output, the input reports are also zero-padded 64 bytes.

 

Unlike the output, there is no length tag at the beginning of the message. The message consists purely of replies.

A "reply" consists of the command ID (one byte), followed by one or more bytes. There is no length tag, so the host must know how long each command's reply will be.

 

Typically, (though not always), the first byte of the reply will be the command opcode. Therefore, if I issue "B7 09 AA", the reply will be "B7 09 XX XX" (where XX XX are the contents of register AA).

 

The responses to the commands above are:

06 - A single '06' is sent in reply, as an acknowledgement of the write

07 - A single '07', followed by the byte in the register requested.

08 - A single '08', as an acknowledgement.

09 - A single '09', followed by the two-byte contents of the register.

0A - A single '0A', as acknowledgement.

0B - A single '0B', followed by the length byte, followed by the register contents.

 

Registers (on my H100i):

 

[TABLE=head]Number | R/W | Length | Description

00 | R | 1 byte | Identifier 1 - for my H100i, 0x3c

01 | R | 2 bytes | Identifier 2 - for my H100i, 0x05 0x10

02 | R | 32 bytes? | Product name, zero-terminated - for me, the string "H100i"

03 | ? | ?? | Unknown, possibly reserved

04 | RW | 1 byte | Select current LED

05 | R | 1 byte | Number of LEDs

06 | RW | 1 byte | LED mode - 00 for static color, 4b for 2-color cycle, 8b for 4-color, c0 for temperature mode

07 | R | 3 bytes | LED current color, RGB color of the selected LED

08 | ? | ?? | ?? Unknown, reserved?

09 | RW | 6 bytes | LED temperature-mode temperatures: 3 temperatures; used when cycle mode is 0xc0

0a | RW | 9 bytes | LED temperature-mode colors: RGBx3 colors, corresponding to temperatures in register above

0b | RW | 12 bytes | LED cycle colors: RGBx4 colors (only first color used if cycle mode set to 00, first two if 4b, ignored if c0)

0c | RW | 1 byte | Select active temperature sensor

0d | R | 1 byte | Number of temperature sensors

0e | R | 2 bytes | Temperature as measured by selected sensor

0f | ? | ?? | ?? Unknown, reserved?

10 | RW | 1 byte | Select current fan; for H100i, 0-3 are the fans, 4 is pump

11 | R | 1 byte | Number of fans

12 | RW | 1 byte | Fan mode; 02=fixed PWM, 04=fixed RPM, 06=default, 08=quiet, 0a=balanced, 0c=performance, 0e=custom

13 | RW | 1 byte | Fan fixed PWM, 0-255, only used if fan mode is 02

14 | RW | 2 bytes | Fan fixed RPM; when fan mode is 04, controller will target this RPM

15 | RW | 2 bytes | Report external temperature to fan controller - used for controlling fans via external sensors

16 | R | 2 bytes | Current fan RPM

17 | R | 2 bytes | ?? Some sort of fan sensor - no clue what this does.

18 | ? | ?? | ?? Unknown, reserved?

19 | RW | 10 bytes | Fan RPM table, for custom (0e) mode: array of 5 RPMs

1a | RW | 10 bytes | Fan temp table, for custom (0e) mode: array of 5 temperatures

[/TABLE]

 

Note: All data is little-endian.

Temperatures are reported in units of 1/256th of a degree Celsius.

 

Example:

 

If I send:

18 02 06 06 00 03 0a 0b 0c 00 00 00 ff ff ff ff
ff ff ff ff ff 04 0b 07 03 00 00 00 00 00 00 00
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00

 

This is a 0x18-long message containing the following commmands:

ID 02, opcode 06: Set register 06 to 00 (turn off LED color cycling)

ID 03, opcode 0a: Set register 0c (LED colors) so the first color is black (off)

ID 04, opcode 0b: Read 3 bytes from register 07 (verify LED color changed)

 

The device will reply:

02 06 03 0a 04 0b 03 00 00 00 00 00 00 00 00 00
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00

 

Broken down:

02 06 (device acknowledges command ID 02 with an 06)

03 0a (device acknowledges command ID 03 with an 0a)

04 0b 03 00 00 00 (replies to command ID 04 with 3 bytes: 00 00 00, confirming LED is now off)

Edited by CFSworks
No longer WIP!
  • Like 1
  • Confused 1
Link to comment
Share on other sites

  • Replies 185
  • Created
  • Last Reply

Top Posters In This Topic

Great job. It's really sad that Corsair choose not to share this information with us, given that the available software is Windows only and full of bugs and misdesign. It's really about time to release this protocol Corsair, so we can use the hardware we've bought.
Link to comment
Share on other sites

you guys are just talking to yourselves,Corsair has responded to this question numerous times,im sure itll be the same as all the times before.

of course you bought the software but not the coding and structure of it.

Edited by wytnyt
Link to comment
Share on other sites

I'm not exactly glued to this forum, so I might have missed those replies - but the last time I read about it there were some excuses about being able to disclose other companies propretary protocols, and that they would do their best to be able to share or something like that.

 

I'm sorry, but that just isn't a proper answer to me. I'm only asking about the Corsair Link protocol, to communicate with the "commander". I don't need access to the source code for the current Corsair Link software, which reads all kind of proprietary hardware device information. To be honest, I'd much rather code something simple and working, then trying to "fix" the software as it is today. All I would be interested in is something taking a minimum of resources, stable that would do it's job without a over-designed, resource hogging, crashing GUI. Personally I wouldn't even care about the LED part, I just want a programmable, reliable fan controller - which is what I thought I bought.

 

I just want a chance to use the hardware I've bought. I don't actually care that much that the software is crap, if we could only have the choice to make our own. I honestly don't think that's asking to much.

 

*edited the confusing typo above

Edited by Nadar
Link to comment
Share on other sites

you're asking for something that simply cant be done due to many factors and obligations that arent controlled by corsair such as infringement rights and such.you dont need to be here on a regular basis to know this,a search would show many topics regarding this subject.

even more this is a windows based software and not designed for linux and obviously this is a known fact.,and is a program that does its intended purpose as evidenced by my 3 sig. units.

you really cant blame corsair for not doing something they legally cant do,

 

To be honest, I'd much rather code something simple and working, then trying to "fix" the software as it is today.

 

you have the software,rework it

my son runs his on linux,so it shouldnt be difficult

Edited by wytnyt
Link to comment
Share on other sites

You didn't understand much of what I said, did you? I'm not talking about the software, but the protocol to communicate with the hardware called Corsair Link the we have bought and can't use.

 

Btw, if your son runs this software on Linux he's either a great magician or he's using some emulation software like Wine or a virtualisation software with a Windows VM like I am.

Link to comment
Share on other sites

You didn't understand much of what I said, did you? I'm not talking about the software, but the protocol to communicate with the hardware called Corsair Link the we have bought and can't use.

 

It's a simple misunderstanding. In your last post, you said "I just want a chance to use the software I've bought." - you undoubtedly meant to say hardware but this left wytnyt confused as to what you meant.

 

But yes, I agree with you 100%: While it's understandable that Corsair cannot release their Corsair Link 2 software source code (and, being a freeware product, it's not like we're "not getting our money's worth" for them not releasing it), it would be nice if they would at least throw us a bone and give us the raw details on how the hardware works. We are, after all, a community of hardware hackers. It's not like we're too stupid to understand.

 

The good news is that I've figured out enough registers (documented in the first post) that anyone can now write their own H100i driver! :D:

 

The bad news is, I don't know if this information is relevant to all Corsair Link devices. It would be lovely if someone else with C coding experience could test out my unofficial spec on one of their devices to see if everything still checks out. (I could probably even write my own open-source command-line Corsair Link utility, if enough people are willing to test it on their own unique setups.) That way, when I start on my Linux driver, I can be sure it's not H100i-specific. Otherwise, the progress so far is pretty swell, I think!

 

EDIT: Oh yeah, and the Corsair Link 2 software will not work on Wine. The Wine project hasn't implemented HID support yet. I'd like to write a Linux kernel driver, though, because then the Corsair Link devices will show up like any other fan/temperature/LED device and be fully compatible with existing Linux system management software.

Edited by CFSworks
Link to comment
Share on other sites

The good news is that I've figured out enough registers (documented in the first post) that anyone can now write their own H100i driver!

a experienced ''software hacker'' wouldnt need to come here and ask corsair for help.theres tons of software programs that allow one to code as they like but the norm is to use someones elses hard work for their benefit.

Link to comment
Share on other sites

a experienced ''software hacker'' wouldnt need to come here and ask corsair for help.theres tons of software programs that allow one to code as they like but the norm is to use someones elses hard work for their benefit.

What are you trying to say? What you just wrote makes no sense to me..

Link to comment
Share on other sites

Since you won't rephrase, I'll just have to guess.. first you're probably trying to insult someone by saying that whoever being the "software hacker" you're referring to isn't experienced enough. First I wonder "experienced enough" by who's standards? Is there suddenly a hacking competition here? Second, you're wrong - CFSworks was the one that interpreted the protocol for the H100i. I was the one that commented that Corsair should share the full protocol.

 

The reason for this is simply that it's so much simpler to make a software where you know the full protocol and doesn't have to guess and make trials and errors. It also reduces the chance of possibly damaging some of the hardware, even though that is probably pretty low risk anyway. It's also much more logical to get that information from the source with a complete description that covers all hardware, instead of someone having to buy all supported hardware to figure it all out. I also can't see any reason for Corsair not to do this, they sell the hardware, which we have paid for, and "give away" the software, so it's not like having some alternative software would hurt their sales. Quite the opposite.

 

The to the really cryptic bit: ".theres tons of software programs that allow one to code as they like". Here I have no clue what you mean, are you referring to all the different development softwares out there, or what exactly are you trying to say? The only thing I can answer is that it doesn't matter in what language/compiler or IDE/editor you use, you have to know what to tell the Corsair Link hardware to achieve what you want. This isn't about using someone else's code, but to have a protocol description (that is, a document that describes commands/replies to the hardware). Alternatively we'd have to develop our own hardware, and what would be the point of buying the Corsair Link devices then?

 

About "the norm is to use someones elses hard work for their benefit." again I don't know who's norms you are referring to, but this is completely beside the point in this discussion. To repeat myself, I really don't care about the source code for the existing software. I only want to know how to correctly, completely and safely communicate with the hardware.

 

Btw., who's benefit are you talking about? We, the customers', benefit by being able to use the hardware we've bought? Or do you suggest that someone would want to make an alternative software to the free Corsair Link software and then sell that for money? If so, I'd just like to wish them good luck with wasting their time... I seriously don't think you understand the different concepts here.

Link to comment
Share on other sites

geezus ,im not trying to insult anyone,im simply saying IF you knew how to code and make a software program,why would help be needed from corsair?

and what happens IF corsair did give it up and it messed up things,who would get the blame?

surely NOT the user.

honestly i wouldnt give something up for free that took tons of time and money to produce.

and i know --you just want it to work--well it does just use windows like it was designed to do.

these why cant i have your source code,protocols threads pop up every week and its been answered tons of times but i guess looking up threads is too time consuming or its like my grand daughter where if she keeps asking ill finally give in just to shut her up.

just ask yourself this

if you spent a small fortune on something,would you just give it away>?

Link to comment
Share on other sites

im simply saying IF you knew how to code and make a software program,why would help be needed from corsair?
There are a bunch of different ways to say something, or to code something, and some programming languages don't look like other languages at all.

 

Programming is different from software / hardware engineering. In any case, they're asking about protocols, not code.

 

Think of it this way - listen to an old 56K modem. Tell me exactly what all of that sound means without help. It's absolutely normal for someone to ask for help, even experienced coders ask for help all of the time. Different experiences / specialties, etc.

 

 

Back to the question on hand - will they release information on the protocols? Who knows. Depends on who designed it, who engineered it, licensing, patents, etc. I don't believe they've commented on the protocols as of yet.

Link to comment
Share on other sites

Back to the question on hand - will they release information on the protocols? Who knows. Depends on who designed it, who engineered it, licensing, patents, etc. I don't believe they've commented on the protocols as of yet.

 

Glad to have you in the thread, Wired! Though you don't work for Corsair, do you have a contact there that you can forward this thread to? I'm just starting on my driver (finally figured out how to read the temperature sensors). If anyone at Corsair wants to put me in touch with the engineer who designed this protocol, it'd be a huge help. Otherwise, I'm sure I can manage on my own. :biggrin:

Link to comment
Share on other sites

Sorry, I don't have contacts on the engineering side. If they haven't seen this thread yet (long holiday weekend and all) they probably will soon enough, but threads like this usually fall under the "no comment" umbrella.
Link to comment
Share on other sites

CFSWorks, you're a hero. I thought about sniffing USB data via a Windows VM earlier, but instead I threw the whole link system in the trash yesterday... better grab it before the trash trucks show up. I look forward to writing software to control this thing but I don't do Linux drivers. We could do so much, if only we could ditch the Link software.

 

Q for the engineers: Why didn't you include non-volatile memory on the Link Lighting so my rig won't default to Christmas tree colors when it boots? I can't sell PCs with this product included, it comes off as unfinished. An SDK isn't going to cut it with most folks I think, perhaps you should acquire rights to the source code, or write your own. I smell a bad investment otherwise.

Link to comment
Share on other sites

Wow, I actually have people registering on the forum to thank me. Never had that happen before... :)

 

I look forward to writing software to control this thing but I don't do Linux drivers.

 

The really lazy way to interface with the Corsair Link, which I have been using, is to look for the /dev/hidraw# device file associated with it and use Python (or the scripting language of your choice) to open it and send/receive HID messages. As long as the reads and writes are exactly 64 bytes each, you should be good to go. If you screw up, the device will reset itself and you'll have to reopen the hidraw.

 

That said, I'm really curious to know how much of this works across all Link devices, so please let me know how it goes! I'm especially eager to know the contents of your 00, 01, 02, 05, 0d, and 11 registers. :D

Edited by CFSworks
Better diction
Link to comment
Share on other sites

  • Corsair Employee

CFSworks,

First thank you for taking the time to create this post and report what you found so far. There are some issues as mentioned previously about releasing the source code. Honestly, we wanted to have the source code available a long time ago for this purpose but that was just not an option for the current product. We will get with the Product Manager and see what information can be released but as far as I know we are not allowed to release any source code at this time due to other agreements.

Link to comment
Share on other sites

Thanks, RAM GUY! Although, as helpful as having source code (to either the software or firmware) would be, I understand completely if that's not available. In that case, the biggest help would be if someone at Corsair could go over my post and either confirm or correct it.

 

Particularly, I'd like to know the secret behind those ID numbers (in registers 00 and 01), what those unused registers do (are they reserved?), and what fan attribute is being measured by 0x17.

 

Thanks again!

Link to comment
Share on other sites

  • Corsair Employee
I cant get into much detail but what you have listed is basic USB protocols and can be found on line. What we cant release is the specific Code or registers for the Link products which is what you are asking for but with a little trail and error you might be able to figure most of it out. Cool Guy is aware and cannot comment but he will when he has some time do what he can but we are strictly limited as to what we can say.
Link to comment
Share on other sites

I threw the whole link system in the trash yesterday... better grab it before the trash trucks show up.

 

If you decide you don't want it let me know and I'll take it off your hands. I'll pay shipping of course :D:

Link to comment
Share on other sites

  • 3 weeks later...

Hey, write a Windows version, too! Just a tiny little efficient (command-line?) app that could be run as a background service - no frills necessary. Throw in SNMP support too for nice, useful MRTG/RRDTool-esque long-term graphing capabilities on the status of my fancy AXi PSU. :p:

 

*Well, I can dream, can't I?* ;):

Link to comment
Share on other sites

  • 2 weeks later...

Has any progress been made on the driver or potential release of the protocol information?

I'd love to dual boot windows 7 (maybe 8 soon), and Ubuntu for software development purposes (especially when it comes to graphics programming), but am hesitant to because there isn't any support from Corsair for Linux yet.

Link to comment
Share on other sites


×
×
  • Create New...