View source for Foccci

Disclaimer: This Page is still work in progress! Any information written here is a draft only and should be handled as such. Contributions more then welcome. If you have questions please ask them in the discussion section of the page or in the OpenInvert Forum.
[[File:Foccci pinout.svg|thumb|Foccci (v4.5) pinout]]


[[File:Foccci 4.5b pinout.png|thumb|Foccci 4.5b / 5 / 5.1 pinout]]
This page is about FOCCCI. FOCCCI is an open source CCS Charge Interface started by Uhi and developed by the OpenInverter Community.

Foccci is the hardware part, and on it runs the software Clara.

Here you will find documentation on the Hardware (and Clara software), where to get it (or how to build it yourself), News regarding the development and many more great things.



Video presentation: https://www.youtube.com/watch?v=Bc7lXPGtLXY



[https://openinverter.org/shop/index.php?route=product/product&product_id=79 Foccci for sale on OpenInverter Shop]

[https://github.com/uhi22/foccci Foccci on Github.]

[https://github.com/uhi22/ccs32clara Clara on Github.] 

[https://openinverter.org/forum/viewtopic.php?t=3727 Foccci in the OpenInverter Forum.]

== Pin description ==

=== External connector ("Deutsch Header") ===
Starting version 4.5b the pins were reshuffled to allow one wiring loom going to the charge port and one to the car side. Changed pins are '''bold'''. [[Connector Part Numbers#FOCCCI|Connector part numbers]] are on a separate page.
{| class="wikitable"
|+
!Short name
!Pin up to version 4.5a
!Pin for version 4.5b, 5, 5.1
!Description
|-
|TEMP1
|A1
|A1
|Power pin temperature sensor. It is pulled up to 3.3V with 10k and the sensor must pull down to GND. Sensor characteristics are configurable in software
|-
|TEMP2
|A2
|A2
|As above
|-
|TEMP3
|A3
|A3
|As Above
|-
|LOCKFB
|A4
|A4
|Feedback signal from connector lock. Pulled up to 3.3V with 10k, so feedback must pull down to GND. Thresholds configurable in software
|-
|IN_U_HV
|A5
|'''B10'''
|Analog input 0 to 5V, with pull-down-resistor. Can be used to measure the charge port voltage, using a converter board, e.g. the "muehlpower board"
|-
|CP
|A6
|A6
|CP (Control Pilot) pin from charge port
|-
|SW2(_LS)
|A7
|'''B4'''
|Output for charge port contactor 2. Low side switch until Foccci 4.4, high side switch starting 4.5
Controls one of the contactors to make the connection between the HV battery and the vehicle inlet.

The output can drive inductive load without additional circuits. It will clamp the turn-off voltage to ~40V. The driver has protection against shortcut and thermal overload.

The output can be configured to be just digital on/off, and can also be configured to use PWM. BUT: In Foccci versions 4.2 and 4.3 (maybe more) the output driver is only capable of slow PWM, which is hearable and may cause trouble with the contactors. So it is recommended to NOT use the PWM feature, and instead use contactors which do not require economizing or use external economizers. In case you want the PWM nevertheless, you need a external freewheeling diode.

Starting Foccci 4.5 PWM is working as intended at 18 kHz. It is a high side output starting v4.5, so the other side of the contactor must be connected to GND. Before v4.5 it is a low side output so the other side must be connected to 12V
|-
|LOCK_MOT2
|A8
|A8
|Motor driver output for charge port lock servo
|-
|LOCK_MOT1
|A9
|A9
|
|-
|PP
|A10
|'''A5'''
|PP (Proximity Pilot) pin from charge port. If you want Foccci to wake up when an unpowered charge cord is plugged in you must close JP3 to pin 1 (towards R7). There mustn't be a pull-down resistor in the charge port in this case as that would permanently keep Foccci awake
|-
|5V
|A11
|'''B11'''
|5V, 500mA e.g. for supplying voltage sense board. This is an OUTPUT of Foccci. Do not apply an external voltage source here. Foccci contains a step-down-converter from the 12V supply to this 5V output.
|-
|GND
|A12
|'''B12'''
|
|-
|CANH
|B1
|B1
|CAN communication
|-
|CANL
|B2
|B2
|
|-
|n.c.
|B3
|
|Unused pins were assigned GND in 4.5b
|-
|n.c.
|B4
|
|
|-
|GND
|B5
|B5, '''B3'''
|
|-
|SW1(_LS)
|B6
|B6
|Output for the charge port contactor 1. See description of SW2(_LS).
|-
|WAKEUP
|B7
|B7
|Wakeup bus. Momentarily (or constantly) applying 12V wakes up the board. In the other direction Foccci can wake up (or supply with up to 1A) other devices via a 12V high side switch
|-
|12V
|B8
|B8
|Supply voltage, always on. 9 to 24V are fine.
|-
|LED_RED
|B9
|'''A12'''
|Status LEDs
|-
|LED_GREEN
|B10
|'''A11'''
|
|-
|LED_BLUE
|B11
|'''A10'''
|
|-
|BUTTON
|B12
|'''A7'''
|Wakes up Foccci or stops an ongoing charging session
|}

=== Internal connectors ===
{| class="wikitable"
|+
!short name
!description
|-
|UART TX
|Provides logging information, 921600 Baud. See also https://github.com/uhi22/ccs32clara/blob/main/doc/clara_user_manual.md#serial-logging
|-
|UART RX
|Not used
|-
|SWCLK
|for flashing with STLINK
|-
|SWDIO
|for flashing with STLINK
|}
== Integrating Foccci with your car/BMS==
[[File:Foccci CCS2.png|thumb|Foccci with (Orion) BMS]]
Depending on your use case Foccci has to communicate with one or more components in your car. All in-car communication happens via a single CAN bus.
===Basic communication considerations ===
Foccci can be configured to run at various baud rates and defaults to 500k. The Wifi interface mentioned below is hard coded to 500k. So when configuring a different baud rate you will loose communication with the Wifi interface. This might be fixed in the future by allowing variable baud rates for the wifi interface. Bottom line: '''keep it at 500k.'''

Apart from that it is mostly sufficient if Foccci can communicate, or more precisely, listen to the BMS. Foccci uses the flexible [[CAN communication|CAN mapping]] known from other OI firmware. There are 5 key parameters that need to be received via CAN:
*'''ChargeCurrent''': this is the single most important item. It is directly relayed to the charger and specifies the current the battery can accept at the given moment. This depends on battery voltage, temperature and other things to be determined by the BMS. ''Foccci itself does no battery monitoring of any kind, it is completely down to the BMS to specify a safe charge current'''''.''' When this value is not updated for more than 2 seconds the charging session is terminated.
* '''BatteryVoltage''': this item is important for precharging the CCS chargers output to the momentary battery voltage. Most BMSes output the total pack voltage in a CAN message
* '''TargetVoltage''': In theory this is the maximum voltage you want the battery to be charged to. In practise the maximum battery voltage MUST be governed by specifying an appropriate ChargeCurrent. More importantly many chargers cut back charge power when ''approaching'' this voltage resulting in poor charging performance towards the top end. So in practise you want to set this to a voltage about 10V above charge end voltage of your battery.
*'''soc''': This is purely informative as far as we know. It displays the batteries state of charge on the chargers display
*'''enable''': this is optional as it defaults to always enabled. It can be used to completely terminate the charging session by setting it to 0.
===Using Foccci as a charge coordinator===
This topic is still work in progress. The CCS connector, as its name suggests, combines both AC and DC charging in one socket. As long as we use the socket only for DC charging it is very easy to wire up. But once we also use the AC functionality we have to spend further thought on this.

The two pins PP and CP communicate information about the cable limit and the momentary current limit of the AC outlet. PP is a simple resistor between PE and PP that is evaluated by putting a test current onto it. This concludes that this signal can only be used by one device. CP is a bit more complex. When plugging in it communicates with a 2k7 resistor to PE that the cable is now connected to a car. From this simple fact we can again conclude that CP is a peer-to-peer signal only. Once the car is ready to charge it switches another 1k3 resistor in parallel to the 2k7 resistor. Only then the AC voltage is switched to the power pins. Lastly, the AC outlet encodes the momentary current limit in a PWM duty cycle.

Foccci does all the evaluation and makes the result available as spot values that can in turn be mapped to CAN:
*EvseAcCurrentLimit
*CableCurrentLimit
To activate the 1k3 resistor aka activating the AC outlet we map AcObcState. It must be set to 2 for activation.

Some chargers want to evaluate the CP (and perhaps PP) signal themselves. This issue can be solved with a change over switch that disconnects Foccci from CP while AC charging. Alternatively the CP signal can be spoofed and the charge current controlled by CAN to satisfy the limits of the AC outlet (EVSE).
== Wakeup ==
For charging it is particularly interesting to wake up Foccci itself and necessary subsystems <ref>https://openinverter.org/forum/viewtopic.php?p=66547#p66547</ref> when plugging in a charge cord. To allow for this, Foccci has various wakeup sources and also can wake up other devices. For wakeup to work, Foccci must be permanently supplied with 12V (it will draw no current when asleep). '''Hardware version V4.5 and above required for wakeup.'''

Here are the sources:

# Wakeup pin - bidirectional - level triggered (12V)
# Button - level triggered (GND)
# PP - optional via solder bridge - level triggered
# CP - Edge triggered

So the first 3 inputs will force the Foccci on. It can't turn itself off as long as that wakeup source is active. The last input will only trigger when transitioning from invalid to valid PWM and then Foccci can decide how long to stay awake. All modes always work regardless of software settings - except PP wakeup which can be turned off in hardware (JP3).

The wakeup output on the other hand is software-defined. Foccci offers the following options

# '''Level''' - as long as the Foccci doesn't decide to turn off, we keep Wakeup on as well
# '''Pulse''' - When Foccci boots generate a 1s wakeup pulse
# '''LevelOnValidCp''' - As long as CP is pulsing we keep wakeup on
# '''PulseOnValidCp''' - Whenever we transition from non-pulsing to pulsing CP we generate a 1s pulse
# '''LevelOnValidPp''' - As long as PP is valid keep wakeup on

The output can supply about 1A and 12V. When running loads larger than that (e.g. a pump) use a relay to amplify the current capability.

It depends on your vehicle architecture how you organize the wakeup. Here are some examples:

=== Basic wakeup ===
wakeup via PP enabled, WakeupPinFunc=LevelOnValidPp

# Foccci turns on as soon as even a non-powered charging cable is plugged in
# Wakeup signal is turned on
# BMS, VCU etc. is turned on (directly powered from wakeup as it can supply about 1A)
# VCU can detect via the level of the wakeup signal that a cable is plugged in and inhibit drive
# When charging cable is unplugged (as in PP lost), Wakeup is turned off and the VCU can allow driving
# If we wanted to report e.g. welded charge port relays Foccci would have to keep itself running until the car is started in drive mode again. Then something can be displayed on the instrument cluster. Of course this will time out eventually. Should be fine as you at least have to pull away from the rapid charger after charging.
# When charging is paused all ECUs stay on and consume 12V power (or HV power via DC/DC)

=== Advanced Wakeup ===
wakeup via PP disabled, WakeupPinFunc=PulseOnValidCp. Here we have a bidirectional wakeup bus. Any ECU connected to it can send or receive wakeup events and the individual ECUs can decide whether they are needed for a particular task or not.

# Foccci turns on as soon as CP PWM starts. So either a cable is being plugged in or is already plugged in and now wants to charge
# It then turns on the wakeup output for 1s and wakes up all other ECUs
# The relevant ECUs will detect that we want to charge and stay on, the other ones turn off
# If we turn on ignition the VCU is already on and in charge mode and can inhibit drive
# If charging is paused (i.e. cable plugged in but no CP PWM) and we turn on ignition the VCU wakes up the Foccci and queries PP status. If something is plugged in drive is inhbited
# If Foccci detects an error e.g. welded relays, it stores that error to flash. When woken up by the VCU it report its non-zero error code
# When charging is paused, ALL ECUs can turn off and no 12V power is consumed. When CP comes back, the cycle restarts

The second approach is more versatile but it also means all devices need to support this method.

So I think there can be an intermediate approach:

=== Semi-advanced wakeup ===
Here we only have a wakeup bus between VCU and Foccci. All other devices are powered up by other means, like VCU controlled relays. Wakeup via PP is disabled, WakeupPinFunc=LevelOnValidCp

# Foccci turns on as soon as CP PWM starts. So either a cable is being plugged in or is already plugged in and now wants to charge
# It then turns on the wakeup output this waking up the VCU
# The VCU determines via CAN message from Foccci whether we want to AC or DC charge and turns on needed components. Components needed in both cases that have low power consumption (e.g. BMS) can also be driven from the wakeup signal directly
# If we turn on ignition the VCU is already on and in charge mode and can inhibit drive
# If charging is paused (i.e. cable plugged in but no CP PWM) and we turn on ignition the VCU wakes up the Foccci and queries PP status. If something is plugged in drive is inhbited
# If Foccci detects an error e.g. welded relays, it stores that error to flash. When woken up by the VCU it report its non-zero error code
# When charging is paused, ALL ECUs will turn off and no 12V power is consumed. When CP comes back, the cycle restarts

== Configuring Foccci via CAN ==
Foccci exposes only one single CAN interface for vehicle communication and initial configuration. So we need a CAN counterpart to talk to it.

There are two main approaches to this: a) use a command line tool <ref>OIC https://openinverter.org/forum/viewtopic.php?t=2907</ref> or b) use an ESP based CAN module <ref>ESP32 CAN Web Interface https://openinverter.org/shop/index.php?route=product/product&path=59&product_id=78</ref>

Both ways require knowing Focccis so called Node Id (similar to an IP address on a local network). By default this is 22. You can enter this node id on the bottom left navigation bar.
== Parameters==
{| class="wikitable"
|'''Name'''
|'''Unit''' 
| '''Min'''
|'''Max''' 
|'''Default'''
| '''Description'''
|-
| colspan="6" |'''Hardware Config'''
|-
|UdcDivider
|dig/V 
|0
|100
|2.63 
|Division factor from ADC digits to V of external voltage measurement board.
In other words: The UdcDivider is the configuration parameter which defines the scaling of the physical inlet voltage measurement circuit. That's why it is only relevant if a physical inlet voltage measurement circuit is present, and if the parameter InletVtgSrc is 1, means the Foccci will measure the inlet voltage with the analog input. CAN mapping makes no sense for the UdcDivider, because it is a fix value. It is the ratio between the voltage on the inlet and the digital value on the AD converter.

For the muehlpower board this value is approx 2.63.
|-
|UdcOffset
|dig
|0
|4000
|572
|Offset for the external voltage measurement board.
To find out the necessary value, apply 0V inlet voltage, and look at the spot value AdcInletVoltage. Take this value and enter it as parameter UdcOffset.
For the muehlpower board this value is approx 572.
|-
|EconomizerDuty
|%
| 0
|100
| 100
|Contactor economizer duty cycle. Contactors are always turned on with 12V for 1s then drop to this value. Set to 100% if your contactor has a built-in economizer 
|-
|InletVtgSrc
|
|0
|2
| 0
|Inlet Voltage Source. There are three option where Foccci gets the CCS inlet voltage from:
0 - Charger output voltage (EVSEPresentVoltage) is considered equal to charge port inlet voltage 1 - Analog input U_IN_HV is used for measuring charge port inlet voltage

2 - Charge port inlet voltage is provided via CAN - don't forget to map something to InletVoltage


The InletVoltage is important for precharging, while the contactors are still open. The car (Foccci) will close the contactors, if the inlet voltage is near to the battery voltage. After closing the contactors, it is the battery voltage (besides some cable losses), and out of interest. The most straight forward solution to measure the inlet voltage is to rely on what the charging station tells us. It reports the voltage on the CCS plug in EVSEPresentVoltage. With configuring InletVtgSrc=0 we tell Foccci to use the EVSEPresentVoltage. In this case, neither an analog inlet voltage measuring circuit nor a separate gadget which provides the inlet voltage via CAN is necessary. For most users this will be fine (even OEM cars use this approach).
|-
|LockDuty
|%
| -100
| 100
|30
|H-bridge duty cycle for operating the lock. Use negative value if lock polarity is swapped
|-
| LockRunTime
|ms 
|0
|10000
|1000
|Timeout for lock operation
|-
|LockClosedThresh
| dig
| 0
|4095
|0
| Lock feedback value for closed
|-
|LockOpenThresh
| dig
| 0
|4095 
| 0
| Lock feedback value for open - if equal to lockclosethr no feedback is assumed and lock is operated timed
We have two cases: (A) "closed" is higher resistance and (B) "open" is higher resistance.
- For (A):

if AdcLockFeedback is low (between 0 and <LockOpenThresh), we detect OPEN.

if AdcLockFeedback is middle (between LockOpenThresh and LockClosedThresh), we keep the last detected state. (or detect "in progess"???)

if AdcLockFeedback is high (above LockClosedThresh), we detect CLOSED.

Example parametrization: AdcLockFeedback is 100 while open, and 1000 while closed. The parameters shall be LockOpenThresh=300 and LockClosedThresh = 800.

- For (B):

if AdcLockFeedback is low (between 0 and <LockCloseThresh), we detect CLOSED.

if AdcLockFeedback is middle (between LockClosedThresh and LockOpenThresh), we keep the last detected state. (or detect "in progess"???)

if AdcLockFeedback is high (above LockOpenThresh), we detect OPEN.

Example parametrization: AdcLockFeedback is 500 while closed, and 3000 while open. The parameters shall be LockClosedThresh=700 and LockOpenThresh = 2700.
|-
| ppvariant
|
|0
|9
|0
|Various circuit variations exist for PP resistor measurement.
"0" is for the variant with 1k pull-up to 3.3V, like old the old Foccci 4.1
"1" is for the variant with 330 ohm pull-up to 5V and 3k pull-down.
"2" is for the variant with 330 ohm pull-up to 5V and NO pull-down.
Foccci 4.5 ususally has NO pulldown, except the related solder jumper was closed.
|-
|WakeupPinFunc
|
| 0
|4
|0
| Configure what the wakeup pin does. See [[Foccci#Wakeup|Wakeup]]
|-
| colspan="6" |'''Communication'''
|-
|NodeId
|
|1
|63
|22
|CANOpen node id for SDO requests 
|-
|CanSpeed
|
|0
| 4
|2
|Baud rate of CAN interface 0=125k, 1=250k, 2=500k, 3=800k, 4=1M - '''when configuring this != 500k you have to change it also for your ESP web interface!'''
|-
| colspan="6" |'''Charge Parameters'''
|-
|MaxPower
|kW
|0
|1000
| 100
|Absolute maximum charge power. Foccci will announce this value in the ChargeParameterDiscoveryRequest message in the element EVMaximumPowerLimit. The charger may or may not respect this limitation. 
|-
|MaxVoltage
|V
|0
|1000
|410
|Over voltage threshold. Always set about 10-20V higher then desired battery full voltage. Foccci will announce this value in the ChargeParameterDiscoveryRequest message to the charger, in the element EVMaximumVoltageLimit. The charger may or may not respect this limitation. Some chargers shut down, if this limit is reached. That's why it is recommended to set it some volts higher than the voltage which is used during normal charging. 
|-
|MaxCurrent 
|A
|0
|500 
|125
| Absolute maximum charge current. Foccci will announce this value in the ChargeParameterDiscoveryRequest, in the element EVMaximumCurrentLimit. The charger may or may not respect this limitation.
|-
|MaxAllowedPinTemperature
|°C
|0
|120
|70
|Temperature of the CCS inlet which leads to fully reduced charge current. If the maximum of temp1, temp2, temp3 reaches this value, the charge current is cut down. Before reaching this limit, the charge current decreases linearily. If the temperature still rises and reaches 10 Kelvin more than parametrized, the charge session will be terminated.
For information purpose, the current limit caused by the temperature is visible in the spot value TempLimitedCurrent. If the limitation is effective, which means, that the BMS would have requested a higher current than the limitation, the spot value LimitationReason shows "InletHot".
In case of massive overheat (10K more than parametrized), the spotvalue StopReason will show "InletOverheat".
|-
|TargetVoltage
|V
|0
|1000
| 0
|Charge target voltage (volatile)
|-
|ChargeCurrent
|A
|0
|500 
|0
| Instantaneous current setpoint (volatile) - must be written at least once per second to prevent [[Foccci#Errors|CANTIMEOUT]]
|-
|soc
|%
|0
|100
|0
|Battery SoC for display on charger (volatile)
|-
|BatteryVoltage
|V
|0
| 1000
|0
| Present battery voltage for precharge state (volatile)
|-
|enable 
|
|0
|1
|1
|When 0 charging is stopped/not started (volatile) - must be written at least once per second to prevent [[Foccci#Errors|CANTIMEOUT]]
|-
|AcObcState 
|
|0
|15 
|0
|Feedback from OBC
|-
| colspan="6" |'''Testing'''
|-
|DemoVoltage
|V
|0
|500
|0
|Voltage for light bulb demo. To use the board without CAN, to get an constant voltage. Is ignored as long democtrl is not STANDALONE. Only values between 150V and 250V are accepted, others are treated as zero. 
|-
|DemoControl
|
|0
|511
|0
|Enables the standalone demo mode if value is set to STANDALONE. In this mode, no CAN is required and the target voltages for precharge and charging loop are taken from demovtg.
|-
|ActuatorTest
|
|0
|7
|0
|Tests various outputs
|-
|logging
|
|0
|2047
|
|Selects which modules log to the serial console
|}
==Spot values ==
{| class="wikitable"
|+
!Name
!Unit
!Description
|-
|opmode
|
|State of the CCS state machine
|-
|version
|
|
|-
|lasterr
|
|Last detected error
|-
|EvseVoltage
|V
|Outlet voltage reported by EVSE
|-
|EvseCurrent
|A
|Outlet current reported by EVSE
|-
|TempLimitedCurrent
|A
|Current limit calculated based on the inlet temperature
|-
|EVTargetCurrent
|A
|Current demand which is communicated to the DC charging station. Is the minimum of TempLimitedCurrent and ChargeCurrent. 
|-
|LimitationReason
|
|Shows the reason why charge power is limited
|-
|AdcInletVoltage
|dig
|Value on the AD converter for the analog inlet voltage measurement. Is the basis for calculation of InletVoltage if the inlet voltage source is configured to "analog input".
|-
|InletVoltage
|V
|Charge port voltage
|-
|EvseMaxCurrent
|A
|Maximum current the EVSE can deliver
|-
|EvseMaxVoltage
|V
|Maximum voltage the EVSE can deliver
|-
|ControlPilotDuty
|%
|The PWM ratio of the CP line. This is normally 5% for DC chargers, and between 10% and 90% for analog AC chargers.
Typical values are explained here: [https://de.wikipedia.org/wiki/IEC_62196_Typ_2 IEC 62196 Typ 2 – Wikipedia]
|-
|temp1, 2, 3
|°C
|Temperatures of the temperature sensors. Requires correct calibration values depending on the used NTC types.
|-
|MaxTemp
|°C
|Maximum of the above
|-
|ContactorDuty
|%
|Duty cycle of charge port contactor driver
|-
|AdcLockFeedback
|digit
|Feedback value from charge port lock
|-
|AdcProximityPilot
|digit
|Analog value of the PP line. This is the raw value of the analog-to-digital-converter in range 0 to 4095.
|-
|ResistanceProximityPilot
|ohm
|Measured resistance between PP line and ground. Requires correct setting of the parameter ppvariant.
|-
|CableCurrentLimit
|A
|Based on the PP resistance. The current limit of the charging cable for AC charging.
|-
|EvseCurrentLimit
|A
|Based on the CP PWM. The current limit of the charging station for AC charging.
|-
|AdcHwVariant
|digit
|raw AD value of the hardware variant coding input. Used to detect which variant of Foccci the software runs on.
|-
|AdcIpropi
|digit
|raw AD value of the current sensor for the charge port lock motor driver.
|-
|LockState
|
|State of charge port lock
|-
|StopReason
|
|shows the reason why the charging session stopped
|-
|checkpoint
|
|shows the progress of the charging session in detail. Explanation here: https://github.com/uhi22/pyPLC?tab=readme-ov-file#example-flow
|-
|CanWatchdog
|100 ms
|Time since last ChargeCurrent update. When it reaches 30 (3s) the charge session is stopped
|-
|VehicleSideIsoMonAllowed
|
|This signal gives Foccci the possibility to control the isolation monitoring on vehicle side.
0: Isolation monitoring shall be off

1: Isolation monitoring shall be on (default)

Background: If we are in precharge, we tell the vehicle side isolation monitoring to keep calm, because the next step will be that the contactors close, and then the charger side isolation monitoring shall be the only one which is monitoring the isolation. Because if we would have two isolation monitors working at the same time, they could/would detect isolation faults by seeing each other.
Discussion started here: https://openinverter.org/forum/viewtopic.php?p=80149#p80149
|-
|cpuload
|
|
|}
==Errors==
The spot value "lasterr" displays the last detected error that lead to a cancellation of charging or to not starting in the first place
{| class="wikitable"
|+
!Error
!Description
|-
|CANTIMEOUT
|The ChargeCurrent or enable hasn't been updated via CAN for more than 2s
|-
|PLCTIMEOUT
|PLC communication with charger timed out
|-
|PRECTIMEOUT
|Precharging the EVSE output to specified voltage timed out or battery voltage is below minimum EVSE output voltage
|-
|LOCKTIMEOUT
|The connector lock didn't reach the desired position in time
|-
|EVSEFAULT
|The EVSE reported an error and stopped
|-
|RELAYWELDED
|A welded charge port relay was detected
|}
== Making Foccci talk CHAdeMO on the CAN side ==
A pretty straightforward way to integrate CCS charging into your vehicle is to use the existing CHAdeMO (let's call it CDM from here on) CAN messaging. CDM has pretty much all data items we need to initiate a CCS charging session, so rather than defining a new set of messages we might as well adopt it. For example, Orion BMS or Zombieverter VCU natively support CHAdeMO anyway.[[File:Can mapping chademo.png|thumb|Screenshot of CAN mapping to interface Foccci CCS with CHAdeMO]]Let's go over the items in the screenshot one by one. Note that the IDs are decimal! (256=0x100, 258=0x102, 264=0x108, 265=0x109)
*'''UdcDivider''' - Actually, here we just select some dummy item as the important bit is in the Offset field: the version. In this case I signal non-existent CDM version 10. This tells the CDM module in my car that it talks to Foccci. It then includes the battery voltage in some unused message bytes - see below.
*'''EvseVoltage''' - Transmits the charger's present output voltage back to the vehicle.
*'''EvseCurrent''' - Transmits the charger's present output current back to the vehicle.
*'''opmode''' - Observe the weird gain - this is forged to map Foccci state "CurrentDemand (13)" to CDM state "ConnectorLocked (4)". In my car's CDM module this is sufficient to initiate the charging progress. You may need to change it so that the ChargeEnable flag together with ConnectorLocked is forged (numerical value 5).
*'''EvseMaxVoltage''' - Transmits the EVSE's maximum output voltage back to the vehicle.
*'''EvseMaxCurrent''' - Transmits the EVSE's maximum output current back to the vehicle.
*'''BatteryVoltage''' - Transmits the present battery voltage to the EVSE.  This is the special item that normally doesn't exist in CDM and that unfortunately will prevent you from using this solution with an OEM car in a safe manner. Of course, you could manually set this to some medium battery voltage like 360V, but if you arrive with a really low battery at, say, 300V this might weld your charge port contactors.  You could also manually enter the battery voltage before each charging session.
*'''TargetVoltage''' - Transmits the charge end voltage to the EVSE.
*'''ChargeCurrent''' - By far the most important data item: the charge current request.
*'''soc''' - In CDM this isn't normally a percentage value but some encoded kWh value.  In my car's CDM module I specify a full battery as "200" (no idea what this actually means in kWh) and thereby can just output the SoC in 0.5% steps.
*'''enable''' - The car's charge enable flag.  When 0 will stop the CCS session.
As an additional safety measure you could connect CDM pin 4 (charge enable) to Foccci's button input (at least once we added an active low mode for it).  It might also be worthwhile to connect pin 7 (connection check) to the PP input for drive away protection when CDM is plugged in but not charging (again, once we have actually implemented this).

Let's list the CHAdeMO pin mapping one by one as well:
*Pin 1 - GND
*Pin 2 (12V, charger start/stop) - 12V (I take it from cigarette lighter)
*Pin 4 (charging enable) - Foccci BUTTON
*Pin 5, 6 - Power pins, triple check correct polarity!
*Pin 7 (Connection check) - Foccci PP
*Pin 8, 9 (CAN) - Foccci CANL, CANH
*Pin 10 (charger start/stop 2) - Foccci SW1_LS
'''<u>Attention:</u>''' with this mapping the error flags are ignored, e.g. voltage or current mismatch.

==Making Foccci talk to boostech BMS==
The boostech BMS has a fixed CAN mapping. It doesn't expect any feedback from the CCS controller so we just keep the CHAdeMO mapping from above in case the info is needed elsewhere in the car.

The BMS sends out big endian messages hence why the length fields are negative. It does not send out a charge end voltage so we simply multiply the charge enable flag with the voltage we want. In the example 368V.
{| class="wikitable"
|+
!Item
!Direction
!ID
!Position
!Length
!Gain
!Offset
!Extended
!Remark
|-
|EvseMaxVoltage
|Transmit
|0x108 / 264
|8
|16
|1
|0
|no
|
|-
|EvseMaxCurrent
|Transmit
|0x108 / 264
|24
|8
|1
|0
|no
|
|-
|EvseVoltage
|Transmit
|0x109 / 265
|8
|16
|1
|0
|no
|
|-
|EvseCurrent
|Transmit
|0x109 / 265
|24
|8
|1
|0
|no
|
|-
|enable
|Receive
|0x310 / 784
|48
|1
|1
|0
|yes
|
|-
|BatteryVoltage
|Receive
|0x310 / 784
|15
| -16
|0.1
|0
|yes
|
|-
|soc
|Receive
|0x310 / 784
|47
| -16
|0.1
|0
|yes
|
|-
|TargetVoltage
|Receive
|0x310 / 784
|48
|1
|368
|0
|yes
|Put your desired TargetVoltage into gain
|-
|ChargeCurrent
|Receive
|0x313 / 787
|31
| -16
|0.097
|0
|yes
|This value is static, more below
|}
The boostech BMS '''lacks one critical feature''' for rapid charging: a dynamic charge limit. That means ChargeCurrent it always a fixed value that you program into the BMS. It will not cut back when cells are getting full, hot or cold. It can be somewhat mitigated by setting a sane target voltage (e.g. 4.1V x NumberOfCells). The rapid charger will then start to cut back charge current as this voltage is approached. Also by mapping the enable flag the BMS has the possibility to abort the charging session if one single cell voltage or module temperature rises above the safe threshold. In winter you will need to dial back your maximum charge current manually or heat you cells to avoid dendrites.

== Hardware detection ==
[[File:3.3v Addressing Voltage Divider.png|thumb]]
To allow software to reliably detect which version hardware it runs on, in HW version 4.1 a version indication resistor was added. As opposed to some other boards that run at 5.3V, the voltage here is 3.3V.
{| class="wikitable"
|+
!Variant
!R1
!R2
!voltage
!ADC
!-3%
!+3%
|-
| -
|47
|2,7
|0,179
|222
|216
|229
|-
| -
|47
|3,3
|0,217
|269
|261
|277
|-
| -
|47
|3,9
|0,253
|314
|304
|323
|-
| -
|47
|4,7
|0,300
|372
|361
|383
|-
| -
|47
|5,1
|0,323
|401
|389
|413
|-
| -
|47
|5,6
|0,351
|436
|423
|449
|-
| -
|47
|6,8
|0,417
|518
|502
|533
|-
| -
|47
|7,5
|0,454
|564
|547
|580
|-
|4.0 with economizer
|47
|8,2
|0,490
|608
|590
|627
|-
| -
|47
|9,1
|0,535
|664
|644
|684
|-
|4.2
|47
|10
|0,579
|718
|697
|740
|-
|4.3
|47
|12
|0,671
|833
|808
|858
|-
|4.4
|47
|15
|0,798
|991
|961
|1020
|-
|4.5 - 5.2
|47
|18
|0,914
|1134
|1100
|1168
|-
|
|47
|22
|1,052
|1306
|1266
|1345
|-
|
|47
|27
|1,204
|1494
|1449
|1539
|-
|
|47
|33
|1,361
|1689
|1639
|1740
|-
|
|47
|39
|1,497
|1857
|1801
|1913
|-
|
|47
|47
|1,650
|2048
|1986
|2109
|-
|
|47
|56
|1,794
|2226
|2160
|2293
|}
<references />

== Frequently Asked Questions ==

=== Q1: Does Foccci help me for AC charging with a Tesla OBC? ===
No. The Tesla OBC wants exclusive access to the control lines of the charge port. It handles the communications with the AC charging station by its own. This communication means providing the CP Résistance and measuring the CP PWM duty cycle. Foccci can also do this, but there cannot be two instances which do the same things. There is the other case: DC charging. For this, the Tesla OBC is not involved. The BMS needs to send the limits to Foccci, and Foccci performs the communication with the charging station.

=== Q2: Does Foccci create an 1kHz PWM, for controlling an onboard charger via the CP pin? ===
No. The CP pin of Foccci is the vehicle side of the CP line. This means, Foccci can *measure* the PWM duty cycle. It can *not* generate the PWM. If you need to generate a 1kHz PWM for your onboard charger, you could have a look to the Zombieverter.

=== Q3: What is the absolute minimum to start a DC charging session? ===
Foccci has the task, to tell the charging station three important values:

# The actual battery voltage, before the charging starts. The battery voltage is needed during the "precharge" phase, to give the charger the possibility to adjust the output voltage exactly to the battery voltage. This avoids large inrush currents when the contactors between the charger and the battery are closed. Large inrush current would damage the involved components, like contactors and capacitors.
# The target charge voltage. The voltage is chosen usually higher than the actual battery voltage, but lower than the maximum voltage rating of the battery. The charger will not deliver more than this voltage. The voltage limit is effective if the battery is nearly full, the current automatically drops slowly while charging in "constant voltage mode".
# The target charge current. This should be a value which is safe for the battery and cables, depending on temperature, SOC, whatever. The charger will use this demand as long as the target voltage is not reached. This is called "constant current mode".

Normally, these three values shall be provided via CAN bus from the battery management system (BMS). For experimentation, it is possible to set these values directly in the web interface, without the need of a BMS. This is called "DemoMode". Not recommended for real charging session, but ok to test the communication with the charger without having a battery installed.

Foccci needs to have the control, whether the DC contacts of the CCS socket shall be connected to the battery pack or not. For this purpose, two contactors are needed (one between CCS plus and battery plus, and one between CCS minus and battery minus). Foccci has two outputs, to control these two contactors.

Foccci needs a power supply, usually 12V, but everything between 9V and 16V is perfect. To have a permanent wakeup, you connect the 12V also to Focccis wakeup-pin.

That's it.

=== Q4: Besides the absolute minimum, what other features of Foccci are recommended to be used in a real-life scenario? ===

# Map the battery voltage, the target voltage and the target current to CAN signals, which are provided by your BMS. This gives the BMS the complete control about the charge parameters, to achieve a safe and fast charging.
# Connect three LEDs (red, green, blue), 12V, common ground, to see the progress of the communication.
# Connect a button (could be combined with the LEDs) which allows to stop the charging session.
# Connect the charge port lock motor. This allows Foccci to lock the charge plug, to avoid unintended disconnection.
# Connect up to 3 temperatur sensors, which are installed in the charge port or cable harness. This gives Foccci the chance to reduce the charge current in case of rising temperature, to avoid thermal damage of the components.

=== Q5: Can I use Foccci together with an onboard charger? ===
The main purpose of Foccci is DC charging. But since the CCS port is also intended to contain AC pins, Foccci supports the following features for AC charging:

- Foccci measures the PWM duty cycle on the control pilot (CP) pin, which the charging station provides. This is 5% in case of DC stations, and higher values on AC stations, depending on the allowed charge current. (There is also a special case, AC station with digital high-level communication. Foccci/Clara do not support this feature at the time of writing.) Foccci provides the measured PWM duty and the calculated AC current limit via CAN bus, so it can be used by an matching onboard charger, or an intermediate controller like Zombieverter, to control the AC charge current.

- In the other direction, Focccis status LEDs and CP status resistor can be controlled via CAN.

An example of usage of Foccci for AC charging is the integration with Zombieverter. An other possibility would be OBCs which can be configured or programmed to have full control via CAN bus.
=== Q5: I'm missing a certain feature of Foccci, could I add this by myself? ===
Sure. It's all open source. Feel free to experiment, discuss (in the forum or in github issues), and finally make a pull request.

=== Q6: Can I use Foccci also to build a charging station? ===
Not directly. Foccci is designed to play the car side of the CCS communication. For using it on the other side, some things need to be changed:

- generate the 1kHz PWM

- measure the CP resistance

- configure the PLC modem to be an EVSE modem instead a PEV modem

- and the biggest part: write the message handling of the high-level protocol for the charging station.

=== Q7: Does Foccci support Plug&Charge or AutoCharge? ===

# The "big" Plug&Charge according to ISO15118 is not supported. It would require a key infrastructure and a newer version of the EXI decoder software, which is not public available at the moment.
# AutoCharge (which is used by FastNed and EnBW) is supported. This uses the MAC address for identification. Focccis MAC address is calculated based on the serial number of the STM32 controller, and therefore each Foccci has (or at least is expected to have) a different MAC address. Alternatively you can patch the code to enter any MAC address you like.

=== Q8: How can I find out the version of Foccci/Clara, which I am running? ===
Using the web interface, show the spot values. At the top there is the software version of the Clara software. For example "0.42.76.B". The "B" means, it is a build from the github actions. And the 76 means, it is github action build number 76. If the version ends with the letter "R", you have a local build, and should contact the person who provided the binary file regarding the content.

Besides the software versions, there are also different hardware versions flying around. The early hardware versions could be (at least partially) identified by the spot value AdcHardwareVariant and HardwareVariant. Starting from Foccci version 4.5, this number is unchanged until (at least) versions 5, 5.1 and 5.2.

=== Q9: I want to try out a different software version. Where can I find it? ===
Each commit on github, or, in simple words, each change of the software, is automatically build into a binary file by a service called "Github actions". This is also called "Continuous Integration", or short "CI". All the generated binaries are available on the Github action page: https://github.com/uhi22/ccs32clara/actions Click on the headline of a certain run, to see the details, and scroll down to the "Artifacts" chapter. There you find the binary file (for flashing via the web interface) and the hex file (for flashing with the STLink tool).

Each run has a certain number (e.g. CI #90). After flashing a new version, the same number will be shown in the spot value "version" after the "0.42." and before the ".B".

=== Q10: ... Feel ... free ... to .... add ... more ... questions ... here. ===
[[Category:CCS]] [[Category:Rapid Charging]]
[[Category:Charger]]
[[Category:OpenInverter]]