tomek-szczesny / openups Goto Github PK

As for now in the development stage I take the opportunity to dump functional and implementation bits and bobs, especially for the contributors.

Ideally, we would like to maintain the project Wiki in useful state after the project is done.
Of course the user's manual will go there, as well as technical description with varying degree of detail.
I prefer having incomplete but correct source of information, if I had to choose between the two. That's why I intend to maintain it as we progress, at the very least by removing outdated information.

Everyone is welcome to contribute to Wiki, especially because writing extensive documentation in a foreign language is a time consuming process for me.

Unfortunately Wiki is a repository that - as far as I know - cannot be branched. So in case anyone wishes to contribute, let me know here and we'll figure out a way to make this work.

Here's a structure I have in mind:

1. Introduction. What is this project about, feature list etc
2. User's Manual
3. Design Description (System level)
4. Detailed Design Description
   -- Linux Host Software
   -- UPS PCB
   -- AVR Firmware for UPS PCB
   -- BAT PCB
   -- BAT Firmware
   -- Case?
5. Implementation details (not exhaustive, only stuff we wrote down for any reason)

In order to support this different cell chemistry, we should consider:

• Mechanical concerns, how big LiFePO4 cells in their typical sizes are we able to fit,
• A separate 3S1P and 3S2P PCBs with appropriate pack protection (different voltage and current limits)
• Additional options in AVR Firmware (different target voltage of a charger)

Personally I don't plan on using LiFePO4 cells, so everyone is welcome to contribute to this effort.

Currently implemented LM317 requires minimum load of 2.5mA, which may drain batteries when OpenUPS is not in use.

Let's try something more modern:
https://www.mouser.pl/datasheet/2/115/DIOD_S_A0011090771_1-2543362.pdf

• Fixed 3.3V output (no external divider)
• "W5" has EN pin, which we can use to latch this regulator off when the battery is depleted (Input voltage will force it on)
• Even without EN pin, IQ is in uA range (similar to battery protector chip).

Current USB-C application sources 5V 3A only when CC pins are being driven accordingly by downstream device.
Additional transistor should be implemented to force USB output on, in order to support non-compliant devices.
This will be an advanced option operated by PC software.

AVR will most likely end up under the heatsink, so we'll need a slim package for it.

The standard kicad footprint has some 6000 heat sinking vias on the central pad, so maybe we'll require a custom footprint with a reasonable amount, like one or five. AVR is not expected to heat up in a meaningful way.

We are already cornered and we don't even have LEDs yet.

Looks like TPS51397 (5V buck) has no soldering paste defined for its central pad.

It'd be nice to make a thorough review of custom footprints.

Even zyssai's board has a nice logo on it, perhaps we could come up with something of our own?
That is, if we cling to that OpenUPS branding. So far google searches of OpenUPS return some other product...

And of course the open source hardware symbol should land on the board (bottom side, probably).
The bottom side will be mostly empty, so we can put almost anything on it.

Some minor actions to unify schematic convention:

• All GND symbols without visible "GND" label, useless clutter,
• Add "Alt" field for component alternatives, instead of comments on schematics
• Re-enumerate components globally
• Select appropriate sheet sizes to schematics

I keep forgetting about them.

I'm thinking about the following LEDs, driven by MCU:

• green Batt LED: Blinking when charging, solid when charged
• red Batt LED: Blinking when discharging, solid on error (no battery, most likely)
• Green LEDs "power good" for each of three voltage converters: 5V, 12V, Adj
  (Even though some power converters have Power Good outputs, I think it should be driven by a microcontroller)

We could add a "power on" LED but that feels redundant - at least one Batt LED will be on anyway.

Now when we need extra 5x GPIO, the real question is whether we switch to 48-pin AVR, or add I2C port extender...

Since we've committed to USB-PD output, it'd be nice to actually implement it at some point.

The problem is, each user may have different expectations for this port. Someone may mistake it for a power input. Others may wish to charge their laptops off it. All compliant devices require special signalling on CC pins to source current from USB-C, and conversely, should offer a handshake, otherwise we may run into situation of two chargers playing tug of war.
There must be some chip or another to advertise supported modes of operation and avoid damage.

Ideally we want a chip that does all that: Advertise voltage and power options, limited to some sane value like 30W, and drives a switch or a built-in power converter.

One solid candidate is TPS25740, although it seems that it must be accompanied by a separate voltage converter it could control directly. This may be arranged, but again, cost, space, all that stuff.

We could limit the scope of USB PD to 5V output only (that was the original goal), but I can't find chips with such limited scope.
The only suitable chip for this task we've identified so far is IP6518 that is hard to source outside Sinoverse. A Western equivalent would be literally perfect.

To wrap it up:

• We need a chip that can do the talking via DP, DM, CCs
• A solution for generating required output voltages (optionally, we've got 5V source already and 5V-only mode is also fine)
• We've got 5V and 12V high-current sources at our disposal, and 9-24V unregulated rail

The datasheet doesn't say much about a recommended layout, other than 1 page of generic advice, "place everything as close as possible".
The reference design manual has a photo of their EVB: https://www.onsemi.com/download/eval-board-manual/pdf/ncp81599gevb_user_guide.pdf
Clearly they did not care much about distances, and yet it works.

The layout gets complicated, because two such converters must fit next to each other, with active components under the heatsink, and inductor (as well as decoupling caps) must stay outside.

5V converter may need to be moved elsewhere to meet those demands.

There are many MOSFETs on a schematic, that are critical for proper operation of key components: Battery charger, voltage converters, power switches, ORing.
Some are expected to dissipate substantial heat, so mechanical requirements also apply so we can fit them under a heatsink.

NFETs:

• Vds > 30V (Some applications may require up to 24V+12V)
• Vgs (-20 : +20). Narrower range is acceptable, but schematics must be reviewed against that
• SMD, 1mm height max (most likely DFN3x3)
• Ron < 10mR, preferrably much less than that
• Gate charge, ideally below 1uC
• Dual NFETs are welcome as most applications are half bridges

PFETs:

• Used predominantly as ORing diodes
• Vds > 30V
• Vgs (-13 : 0) or anything beyond
• Any SMD package (no serious heat anticipated)
• Ron < 10mR or less
• Dual unit welcome

Access to SPI would be beneficial for the use of an LCD display during firmware development and as an additional UPS feature. It could be used to enhance a standalone case or as a remote display in an integrated server case. No SPI interfaces are currently used so a single header could provide the needed interface if board space and layout allows.

In further research there isn’t any clear SPI connector standards that are widely adapted. The ones that are currently used are from specific makers tied to their products.

• PMOD, a standard by Digilent with 0.1” pin headers, for SPI channels, a 1x6 connector with pin order {SS, MOSI, MISO, SCK, GND, Vcc}

• EYESPY a standard by Adafruit for displays using SPI that also supports I2C for touch screens, using a 0.5 pitch 18 pin FPC connector with pin order {Vcc,LITE,GND,SCK,MOSI,MISO,TFTDC,TFTRST,TFTCS,CARDCS,MEM_CS,TSCS,SCL,SDA,INT,BUSY,GPIO1,GPIO2}

• Beaglebone Blue, 1 mm pitch JST-SH connectors used for SPI channels, a 6-pin connector with pin order {GND, 3.3V, MOSI, MISO, SCK, SS}

The EYESPY is the most interesting because of it’s increased capability and adaptability to different displays. Not all signals have to be used as demonstrated in the breakout board example. By including I2C and the other CS signals in the FPC cable, a touchscreen display is now possible. The schematic and pin order can be found at the downloads page.

If PCB space was unlimited, the ideal situation would be to deploy a full EYESPY FPC connector but also have a 6 pin 2.54mm header for extra flexibility for non compliant LCD displays. Regardless of how far one wants to take this, it seems to me that for the price of a pin header, at least one SPI 6-pin 2.54mm header is justified for basic display capability.

For now I've added XT60PW-M as a schematic placeholder until we settle on the target PCB interconnection.

The cheapest 4-layer process is preferred for UPS PCB. 1.6mm standard thickness.

Fuel Gauge chips are expensive, and the market is dominated by ICs for single cell systems.
This is not a feature that is in demand or necessary, just leaving it here as a possible improvement for the future.

A crude fuel gauge could be implemented on AVR (that already monitors the battery current).
But it should not be attempted at least until the current measurements are proven to be reliable enough.

The microcontoller selection has been narrowed down to 28-pin AVR DA or DB families, either SOIC or SSOP package. For now the development effort assumes either of those, unless it's necessary to narrow down the selection for any reason.
Chip availability is one of the concerns here. We may end up with larger memory model just because of that.

The programming interface is UPDI, and a passive converter to UART will be implemented on PCB. Direct access to UPDI pin will be inherently provided.

avrdude should support this configuration with any 3.3V UART converter, be it FTDI or SBC UART pins directly. The programmer type is serialupdi. Further configuration may be required to select a UART port. The solution is relatively new and thus should be considered risky/unstable. A fallback plan is to use some other programming method via exposed UPDI pin.

Up the development chain, avr-libc appears to support DA and DB families after version 2.1.
Thus I assume avr-gcc should support these chips just as well.

AVR Assembler avra shows no signs of supporting DA/DB families. This only supports the preemptive decision of using C as a language of choice. I can imagine literally nobody being able to work with my ASM code.

As a baseline, AVR will work with maximum clock frequency of 24MHz generated by internal oscillator. As such it's not super precise, but should be reasonably accurate to measure fan RPM, for example.
All power supplies will come from LM317-regulated 3.3V source, and external 2.5V ADC reference generated by TL431 or equivalent.
I2C bus should work at 400kHz in both directions for maximum compatibility and stability. Master bus may be sped up to 1MHz as it will be used only within the PCB.

Code requirements TBD

Investigating a new idea of removing (or significantly reducing) battery supervision microcontroller.

The foreseen benefits include single, centralized firmware on UPS AVR, and removing need for support of a middleman in communication. Also, users will not have to push the button on the battery pack PCB to boot it after assembly. And finally, disconnected battery will actually enter a long term storage mode, and will only work with data link connected.

This is how I see it as of today:

• Internal I2C bus present on UPS PCB gets extended to 2-pin data connector of the battery,
• UPS PCB's AVR can talk to BQ769x0 directly via I2C, and only I2C
• BAT PCB has a mechanism that puts BQ chip into SHIP mode if no I2C activity is detected.

To me it sounds foolproof. It also serves as a protection against AVR failure, a measure unforeseen until now.

SHIP mode may be activated by either sending a special I2C sequence, or forcing the BQ chip to go through POR (Power On Reset). The latter is discouraged by the datasheet.
At the same time, a mechanism that transitions BQ chip from SHIP to NORMAL mode is required. This is achieved by pulling a temperature sensor pin TS1 above 1V threshold for at least 2ms.

The BAT PCB implementation could be a minimal AVR with I2C port and one more GPIO. Attiny 212/412 fits the bill.
During normal operation, it would passively watch SCK and SCL, possibly with its internal TWI peripheral disabled. If it detects no activity (SCK idle for > 1000ms), it will turn on its I2C Master interface and order BQ to go into SHIP mode. AVR will then lose its power source, as I assume BQ's external LDO will be shut down as well (I can't find confirmation for this). If not, AVR will implement sleep mode.

When BAT PCB gets connected to UPS PCB, either AVR will get temporarily powered from the I2C lines, or it will wake up triggered by SCK pulled high. Both of these may be implemented concurrently. It will then wake up BQ chip by pulling its TS1 pin high. From this point AVR will be powered entirely from BQ's LDO.

Alternatively, BQ wake up may be implemented as a I2C command that battery side AVR will detect and execute on demand.

Finally, the battery side AVR may support up to 3 configuration jumpers for user configuration of battery chemistry type. Those may be readable via I2C. One of these pins may be used for programming said AVR via UPDI.

Am I missing anything?

I can't believe that, but yeah, we're doing this, hear me out.

BD99950. Costs about $2, and will do it all:

• Autonomously charge batteries to any voltage, and with any current desired (programmable via I2C)
• Manages switching between AC and battery supply (no ORing diodes!)
• Measures battery current (Analog output, charging only)
• Supports adapter and battery current sharing for transient high current demands (Input current is programmable)
• Learn mode, that forces one-time battery operation until a complete discharge. We could use that for a battery test mode, and calibration of whatever fuel gauge mechanism we will implement.

Yup, this will work with LiFePO4 too. Solves a few problems, but not fuel gauge.

TI seems to offer the same chip, BQ24715, albeit with pinout rotated by 90 degs. Hmmm...

There are more variants available, such as BQ24725A. Appears to be pin compatible as well, except its datasheet does not mention "power boost" support.

I'll implement BD chip because it's the cheapest option, and replace with TI's counterpart in case of shortage.

We've come a long way from a concept of linear charger using a single resistor, isn't it.

Ah, snap. We may need to implement I2C isolator, or some passive hacks to prevent that from happening.

Everything that is exposed outside a case must be protected against ESD, namely:

• I2C
• USB-C

The power IO is less likely to be affected due to high capacitance.

Battery PCB should also get adequate protection.

A fifth hole is to be added somewhere near the connector-filled edge, around the center.
At the same time, some of the existing holes may be moved for better THT cap placement.

These are the old requirements, for reference only. Please see the following posts for current state of affairs.

Please create a separate branch, such as "bat_pcb" for this design.

The battery module consists of three rechargeable li-ion cells connected in series, placed in dedicated cell holders. The module PCB also provides basic protection against overcharging, overcurrent, overheating, as well as balances the cells.

The battery module will support one of two assembly variants:

• For 20700 or 21700 cells (Keystone 246)
• For 18650 cells (Keystone 254)

Functional requirements:

• Three cells connected in series
• Short circuit protection at 12-20A
• Discharge overcurrent protection at 9 - 12A (above 200-500ms)
• Charge overcurrent protection at 3 - 4A
• Overvoltage protection within 4.1 - 4.2V per cell
• Undervoltage cut-off at 2.6 - 3.1V per cell
• Cell balancing at any reasonable rate (10-100mA?), without risk of overheating
• Thermal cell protection within 45-65 deg C range
• Battery pack must recover from any fault conditions without user intervention
• Additional, independent cell temperature monitor routed to UPS PCB (TBD)

Mechanical requirements:

• 2-layer, 1mm thick, 35um copper PCB with SMD components only, on top side only (bottom must be flat and fully isolated)
• Non-plated holes are acceptable
• 4-layer PCB possible if deemed necessary
• PCB dimensions and cell layout TBD
• Cell orientation is arbitrary but must be clearly marked on top silkscreen

Parts:

• Battery holders (datasheets contain recommended layouts):
  • Keystone 246
  • Keystone 254
• BQ77915 family cell protector and balancer (specific part numbers to be selected)
• 2x NMOS TBD (adapted from UPS schematic)
• 0603 passives, except current sense resistor which may be larger

Open hardware licenses do exist, it makes sense to choose one of those.
GitHub does not recommend any license dedicated to hardware.

More work is needed for better case closure due to component interference and size of the battery PCB. Other case types are being considered e.g. snap or fitted top. A different thru-bolt fastener arrangement is also possible and needs to be explored more thoroughly. The battery PCB size may also need to be increased to solve the problem.

I'm thinking about:

• 5V: 4A
• 12V: 5A
• Vadj: 4A
• USB 5V: 4A
• SATA: No fuses. After all, motherboards don't have special fuses for SATA drives.

As stated in the title, I know exactly how hard it is to remove those SMD cans, and solder in new ones on a crowded PCB.

@hominoids, what is a safe estimate of a UPS PCB top side clearance? Can we use 11mm tall capacitors?

Some of them are "complicated"

It used to be necessary for the old ISP ways.

A case have been found in which a battery may discharge into 12V output via charger's buck converter.
To be addressed later - perhaps top level architecture will prevent this from happening somehow.

We will need a suite of programs for basic communication with OpenUPS via I2C port.
Fortunately enough it may be generic for any platform and communicate via /dev/i2cx. I guess?

I think we should lean towards a daemon service openupsd that will interact with i2c, and a client openups that may be used with no special privileges.

Should be written in C/C++ and without exotic libraries (preferably no libraries outside gcc standards).

Some things those programs will do:

openupsd

• exchange data between OpenUPS hardware and openups client
• Makes sure write requests are sane
• Support triggers (No AC, Batt voltage < 10V, etc.) and launch a defined script on first match. To be defined as command line params (easier to deal with in service file)

openups

• syntax: openups [FLAGS] REG1 [VAL1] REG2 [VAL2]...
• --read (-r) : reads REGn, one or more. Each value in new line
• --write (-w) : writes VALn into REGn.
• --verbose (-v) : (script-friendly output by default)
• --info (-i) : spits out everything it knows (-v implied)
• --force (-F) : required for insane writes (such as output voltage above input voltage)
  Bonus points for:
• --interactive : with menus, graphs and ascii-art spinning fans, using notcurses library 🤣

No case sensitivity, supports both dots and commas as numerical separators.
openups should parse its command line parameters and do nothing (exit with error) if anything is ambiguous. We don't want anyone to raise output voltage by mistake.
Exit codes should indicate what went wrong (No answer, wrong answer, garbage input etc).

We will define mnemonics for register names to make life easier for everyone.
For example FAN1, when read will return RPM, and when written will set PWM.

The current baseline is reuse of Odroid C4 heatsink, also compatible with XU4 fan.
I'll need to create heatsink footprint in kicad, if we could put our hands on a reliable CAD drawing of it.

Also needed:

• Temperature sensor under a heatsink,
• XU4 fan connector, for handling the worst case scenario