Why release products without accurate documentation?
-
Today I unboxed an ESP32 wearable in watch form. I was thrilled. Color display, bluetooth, wifi, accelerometer, IR sensor, vibration thing, and a little sound module, all in a tiny package. It was about $50 USD. The default firmware worked great, but I bought it so I could program it. I go to program it. The thing takes fine and uploads, is clearly running - spewing to the serial port, but there is no display. So I try another library. Nothing. So I try another library. Still nothing. So I try the source code for the default firmware. Still nothing. The backlight for the display won't even turn on, which tells me that the pin assignments are completely wrong in the documentation or they're using a different display than the one in the documentation. At this point there is no other possibility, since their default firmware doesn't even work with it when I recompile it. Meaning the source is out of date - doesn't match the hardware. So I've tried to contact them but it's a chinese company so who knows. LilyGo is a brand a lot of people use, but I'm not confident in their support. Furthermore, I got an AI Thinker A1S ESP32 sound board with an unusual codec that nobody supports. The datasheet for it is incomplete. There is no example code that works except one that forks the entire ESP-IDF - and even that one wouldn't actually produce any sound for me. There's $30 wasted. So I've dumped $80 into two development projects that work perfectly hardware wise, but because of lazy people refusing to keep their documentation and sources accurate, complete and up to date they are basically trash. That's the worse part. I know both of these devices work, but I may as well stomp them to pieces. DOCUMENT WHAT YOU MAKE. :mad:
Real programmers use butterflies
You are lucky it were just $80. I once bought a DDR development FPGA board for €1700 from a major European manufacturer and could never get it to work. It came with closed source examples that seemed to work but no project I made ever worked. I looked deeper into the documentation and the pins where the DDR was supposed to connect to the FPGA were wrong (I knew from other earlier tests of mine that some pins were connected to other peripherals like LEDs and a serial console) and even mentioned pins that did not exist in the FPGA that came soldered on the board. I spent some more money hiring support from the manufacturer to complain and, after two weeks, they reluctantly sent me VHDL source code of a project that supposedly they used internally in the company to test the board. The pins were all different from the documentation. And their source did not work either :( . I tried to keep complaining but they just closed the issue as "Fixed" and stopped replying. Eventually I found out, from another unfortunate guy somewhere a few countries over, that the DDR would never work because the board had the connections very poorly routed which added too much noise and transients, and the reason the company's closed source example worked was because it was clocked at 1/16 the normal speed of the DDR (unusable for my project). Regarding your predicament, I try to avoid Chinese companies for gadgets because they rarely have documentation for anything and never give support. They rather have you quit your current gadget and buy another from them. If it is just an integrated circuit they make documentation because they want to sell to other companies that make gadgets. So you might be on your own unless you can find someone that is also working on a modification of those gadgets and could already reverse engineer them. I think products without a functional documentation should not get approved by whomever certifies them because, for me, a product (hardware and/or software) without proper documentation is just trash. Good luck
-
You are lucky it were just $80. I once bought a DDR development FPGA board for €1700 from a major European manufacturer and could never get it to work. It came with closed source examples that seemed to work but no project I made ever worked. I looked deeper into the documentation and the pins where the DDR was supposed to connect to the FPGA were wrong (I knew from other earlier tests of mine that some pins were connected to other peripherals like LEDs and a serial console) and even mentioned pins that did not exist in the FPGA that came soldered on the board. I spent some more money hiring support from the manufacturer to complain and, after two weeks, they reluctantly sent me VHDL source code of a project that supposedly they used internally in the company to test the board. The pins were all different from the documentation. And their source did not work either :( . I tried to keep complaining but they just closed the issue as "Fixed" and stopped replying. Eventually I found out, from another unfortunate guy somewhere a few countries over, that the DDR would never work because the board had the connections very poorly routed which added too much noise and transients, and the reason the company's closed source example worked was because it was clocked at 1/16 the normal speed of the DDR (unusable for my project). Regarding your predicament, I try to avoid Chinese companies for gadgets because they rarely have documentation for anything and never give support. They rather have you quit your current gadget and buy another from them. If it is just an integrated circuit they make documentation because they want to sell to other companies that make gadgets. So you might be on your own unless you can find someone that is also working on a modification of those gadgets and could already reverse engineer them. I think products without a functional documentation should not get approved by whomever certifies them because, for me, a product (hardware and/or software) without proper documentation is just trash. Good luck
Ouch! I don't envy you that 1700 euro experience.
ElectronProgrammer wrote:
a product (hardware and/or software) without proper documentation is just trash.
Amen!
Real programmers use butterflies
-
Today I unboxed an ESP32 wearable in watch form. I was thrilled. Color display, bluetooth, wifi, accelerometer, IR sensor, vibration thing, and a little sound module, all in a tiny package. It was about $50 USD. The default firmware worked great, but I bought it so I could program it. I go to program it. The thing takes fine and uploads, is clearly running - spewing to the serial port, but there is no display. So I try another library. Nothing. So I try another library. Still nothing. So I try the source code for the default firmware. Still nothing. The backlight for the display won't even turn on, which tells me that the pin assignments are completely wrong in the documentation or they're using a different display than the one in the documentation. At this point there is no other possibility, since their default firmware doesn't even work with it when I recompile it. Meaning the source is out of date - doesn't match the hardware. So I've tried to contact them but it's a chinese company so who knows. LilyGo is a brand a lot of people use, but I'm not confident in their support. Furthermore, I got an AI Thinker A1S ESP32 sound board with an unusual codec that nobody supports. The datasheet for it is incomplete. There is no example code that works except one that forks the entire ESP-IDF - and even that one wouldn't actually produce any sound for me. There's $30 wasted. So I've dumped $80 into two development projects that work perfectly hardware wise, but because of lazy people refusing to keep their documentation and sources accurate, complete and up to date they are basically trash. That's the worse part. I know both of these devices work, but I may as well stomp them to pieces. DOCUMENT WHAT YOU MAKE. :mad:
Real programmers use butterflies
I find equipment vendor SDKs to be the worst! Here I am working to enable the use of their products by my customers, and they supply documentation and code samples that are truly useless, even when they work. You'd think they would want to make my life as productive as possible to sell more of their hardware. It all boils down to what is valued by management. There are many examples of severe myopia when it comes to proper methodology, documentation, and QA.
Cheers, Mike Fidler "I intend to live forever - so far, so good." Steven Wright "I almost had a psychic girlfriend but she left me before we met." Also Steven Wright "I'm addicted to placebos. I could quit, but it wouldn't matter." Steven Wright yet again.
-
Today I unboxed an ESP32 wearable in watch form. I was thrilled. Color display, bluetooth, wifi, accelerometer, IR sensor, vibration thing, and a little sound module, all in a tiny package. It was about $50 USD. The default firmware worked great, but I bought it so I could program it. I go to program it. The thing takes fine and uploads, is clearly running - spewing to the serial port, but there is no display. So I try another library. Nothing. So I try another library. Still nothing. So I try the source code for the default firmware. Still nothing. The backlight for the display won't even turn on, which tells me that the pin assignments are completely wrong in the documentation or they're using a different display than the one in the documentation. At this point there is no other possibility, since their default firmware doesn't even work with it when I recompile it. Meaning the source is out of date - doesn't match the hardware. So I've tried to contact them but it's a chinese company so who knows. LilyGo is a brand a lot of people use, but I'm not confident in their support. Furthermore, I got an AI Thinker A1S ESP32 sound board with an unusual codec that nobody supports. The datasheet for it is incomplete. There is no example code that works except one that forks the entire ESP-IDF - and even that one wouldn't actually produce any sound for me. There's $30 wasted. So I've dumped $80 into two development projects that work perfectly hardware wise, but because of lazy people refusing to keep their documentation and sources accurate, complete and up to date they are basically trash. That's the worse part. I know both of these devices work, but I may as well stomp them to pieces. DOCUMENT WHAT YOU MAKE. :mad:
Real programmers use butterflies
-
It's not like I bought cheap components. I paid retail for gadgets that were priced at about what they were worth, if they were usable, that is.
Real programmers use butterflies
-
I think my second calling may have been as a writer. I do okay at technical writing despite no formal training in it. I think my articles here have helped me hone it as well.
Real programmers use butterflies
I really don't like the technical writing, but it's one of those things I know I have to do, for myself and any other developers that come down the line to look at my code. I try to be as accurate as possible with out overloading on details, except embedded; you can never have enough details. I absolutely loathe making user "how to's" and other like documentation.
-
I really don't like the technical writing, but it's one of those things I know I have to do, for myself and any other developers that come down the line to look at my code. I try to be as accurate as possible with out overloading on details, except embedded; you can never have enough details. I absolutely loathe making user "how to's" and other like documentation.
While it's not appropriate necessarily for technical documents (though maybe it should be) I find that the more fun I make something to read, the more fun I have writing it.
Real programmers use butterflies
-
Today I unboxed an ESP32 wearable in watch form. I was thrilled. Color display, bluetooth, wifi, accelerometer, IR sensor, vibration thing, and a little sound module, all in a tiny package. It was about $50 USD. The default firmware worked great, but I bought it so I could program it. I go to program it. The thing takes fine and uploads, is clearly running - spewing to the serial port, but there is no display. So I try another library. Nothing. So I try another library. Still nothing. So I try the source code for the default firmware. Still nothing. The backlight for the display won't even turn on, which tells me that the pin assignments are completely wrong in the documentation or they're using a different display than the one in the documentation. At this point there is no other possibility, since their default firmware doesn't even work with it when I recompile it. Meaning the source is out of date - doesn't match the hardware. So I've tried to contact them but it's a chinese company so who knows. LilyGo is a brand a lot of people use, but I'm not confident in their support. Furthermore, I got an AI Thinker A1S ESP32 sound board with an unusual codec that nobody supports. The datasheet for it is incomplete. There is no example code that works except one that forks the entire ESP-IDF - and even that one wouldn't actually produce any sound for me. There's $30 wasted. So I've dumped $80 into two development projects that work perfectly hardware wise, but because of lazy people refusing to keep their documentation and sources accurate, complete and up to date they are basically trash. That's the worse part. I know both of these devices work, but I may as well stomp them to pieces. DOCUMENT WHAT YOU MAKE. :mad:
Real programmers use butterflies
I have learned to avoid buying from manufacturers that don't speak my language. Getting any real help is a pain. Several years back, I bought a batch of fanless mini-PCs from a Chinese manufacturer to run some digital display boards. (Someone else's pick, but yes, I signed off on it.) When they arrived, I couldn't do anything with them. The BIOS was not fully programmed on any of them. After almost two months of emailing and attempting to use the chat feature on their site (and a couple of international calls to their un-manned support line), I finally got a response from someone with a link to download all the BIOS files and driver files I would need to set the PCs up. It took 8 hours to download less than 20 Meg of files. I think the server must have been a PC under someone's desk with a dial-up internet connection. I flashed the BIOS, installed Windows, installed the drivers, then set up and deployed my display boards. About one week after deployment, the video chips on all of them burned out. I opened the cases to find that there was a piece of foam (not the thermal transfer kind, more like thin packing foam) pressed between the heat sinks and the case. I was left with fourteen PCs dead, two months wasted time and effort, and users calling me an idiot for deploying a bunch of new display boards that looked like a colorful lightning show superimposed over bug races just days after turning them on. It took a long time to live that one down and repair my reputation. From now on, manufacturers have to have a support office in a country that speaks my language before I will buy anything from them. ---------- Money makes the world go round ... but documentation moves the money.
-
I have learned to avoid buying from manufacturers that don't speak my language. Getting any real help is a pain. Several years back, I bought a batch of fanless mini-PCs from a Chinese manufacturer to run some digital display boards. (Someone else's pick, but yes, I signed off on it.) When they arrived, I couldn't do anything with them. The BIOS was not fully programmed on any of them. After almost two months of emailing and attempting to use the chat feature on their site (and a couple of international calls to their un-manned support line), I finally got a response from someone with a link to download all the BIOS files and driver files I would need to set the PCs up. It took 8 hours to download less than 20 Meg of files. I think the server must have been a PC under someone's desk with a dial-up internet connection. I flashed the BIOS, installed Windows, installed the drivers, then set up and deployed my display boards. About one week after deployment, the video chips on all of them burned out. I opened the cases to find that there was a piece of foam (not the thermal transfer kind, more like thin packing foam) pressed between the heat sinks and the case. I was left with fourteen PCs dead, two months wasted time and effort, and users calling me an idiot for deploying a bunch of new display boards that looked like a colorful lightning show superimposed over bug races just days after turning them on. It took a long time to live that one down and repair my reputation. From now on, manufacturers have to have a support office in a country that speaks my language before I will buy anything from them. ---------- Money makes the world go round ... but documentation moves the money.
I don't really have that option as the ESP32 platform itself is Chinese in origin.
Real programmers use butterflies
-
I expect the hardware I purchase to be usable. It's literally not usable. You can't do anything with it. You don't understand. There is no usable datasheet. You can't program against the thing. Imagine you had a C static library with no header and no docs. That's what this is, basically. I can buy any electronics components I want - even for pennies a piece, and they all have datasheets. I expect more for $5
Real programmers use butterflies
-
Get down with reverse engineering. It's like solving a satisfying puzzle when you manage to get something to work!
Trust me, I've been trying.
Real programmers use butterflies