diff --git a/firmware/integration/rusefi_config.txt b/firmware/integration/rusefi_config.txt index 81526591c1..ba00769df6 100644 --- a/firmware/integration/rusefi_config.txt +++ b/firmware/integration/rusefi_config.txt @@ -1,31 +1,49 @@ -! TL,DR https://wiki.rusefi.com/Dev/Dev-Tips/ -! -! this file defines the format of rusEfi persistent configuration structure -! this file is processed by ../java_tools/config_definition.jar tool -! comments start with '!' +! This file defines the format of rusEfi persistent configuration structure +! This file is processed by ../java_tools/config_definition.jar tool +! Comments start with '!' ! ! The format is unique to rusEFI but there is a guide to the format available in java_tools/config_definition/RusefiConfigGrammar.g4 ! -! This file is used in combination with rusefi.input to generate the .ini files used by turner TunerStudio. +! This file is used in combination with tunerstudio/rusefi.input to generate the .ini files used by turner TunerStudio. ! The easiest way to find a specific variable within this config is to search within rusefi.input for the on screen text from tuner studio ! this should provide the actual variable name, for example searching for "Number of Cylinders" will provide the variable "cylindersCount". +! Then you can search for "cylindersCount" in this file to find the definition. ! -! rusEfi configuration consists of two parts: -! First part is engine_configuration_s area, followed by a few tuning tables +! This file consists of two parts: +! The first part is engine_configuration_s area, followed by a few tuning tables. ! -! The only difference here is that engine_configuration_s area does not support hot modification while tuning tables could -! be modified without burning changes +! The only difference here is that engine_configuration_s area does not support hot modification while tuning tables can +! be modified without burning changes. ! -! See also ../tunerstudio/readme.md +! See also tunerstudio/readme.md ! -! Q: How to add new fields? -! A: Find an 'unused' bit or unused int (usually the huge unusedEnd[] array at the end -! rename the bit or substitute unused integer with any new fields of the same size -! invoke gen_config.bat to apply the tools which would generate .h and .ini files +! # Adding new fields +! The most important thing to note when adding fields is that if you change the offset +! of any other fields, users will have their configs scrambled when they update their firmware. +! As a result, this file is an organism that must be handled carefully. You may notice that +! there isn't much organization to this file with fields in amongst unrelated fields. +! That's OK, it's just a result of things being removed and new things being put in their +! places, and new things only being able to be added at the end of the structure or where +! other things were removed previously. +! Find a "padding" field (usually the huge mainUnusedEnd[] array at the end of the structure) +! The standard practice is to name these "unusedSomething", so you can find them easily +! by searching for "unused" within this file. +! Rename or substitute the field with any new fields that total to the same size. +! If you're adding a field to the end of the file, add it just before mainUnusedEnd[], +! and subtract the size of the field you added from mainUnusedEnd[]. +! For example, if you added a uint8_t field, and mainUnusedEnd was `uint8_t[100]`, +! it should now be `uint8_t[99]` +! At this point it's a good idea to save your changes in version control, i.e. with `git commit`, +! so that you can roll back to the current state after you generate the config files. +! This is important because we do not include the generated files in pull requests. +! We have a Github Actions workflow that generates all the files automatically after +! the pull request has been merged. +! Invoke gen_config.sh to generate .h and .ini files. +! Now check the `git diff` to make sure you haven't accidentally changed the offsets of +! any other fields. +! If you did, reset your version control state to your commit, i.e. with `git stash`, +! and fix the fields you created to make sure that they total the same size. ! -! Q: Which files to include into Pull Requests? -! A: Please only include source files (.txt and .input) into a PR, we have amazing GitHub Actions which would do the rest really -! really nicely! ! ! each field is declared as ! type name;comment diff --git a/firmware/rusefi.cpp b/firmware/rusefi.cpp index bffdb60e87..2039831b3c 100644 --- a/firmware/rusefi.cpp +++ b/firmware/rusefi.cpp @@ -84,17 +84,27 @@ * 2.777ms, so we schedule spark firing at '2.777ms after the 690 position sensor event', thus combining trigger events * with time-based offset. * - * @section config Persistent Configuration - * engine_configuration_s structure is kept in the internal flash memory, it has all the settings. Currently rusefi.ini has a direct mapping of this structure. + * @section tunerstudio Getting Data To and From Tunerstudio * + * Contains the enum with values to be output to Tunerstudio. + * console/binary/output_channels.txt + * + * [Changing gauge limits](http://www.tunerstudio.com/index.php/manuals/63-changing-gauge-limits) + * + * Definition of the Tunerstudio configuration interface, gauges, and indicators + * tunerstudio/rusefi.input + * + * @section config Persistent Configuration + * + * Definition of configuration data structure: + * integration/rusefi_config.txt + * This file has a lot of information and instructions in its comment header. + * in order to use CONFIG macro you need EXTERN_CONFIG and include engine_configuration.h * Please note that due to TunerStudio protocol it's important to have the total structure size in synch between the firmware and TS .ini file - * just to make sure that this is not forgotten the size of the structure is hard-coded as PAGE_0_SIZE constant. There is always some 'unused' fields added in advance so that * one can add some fields without the pain of increasing the total configuration page size. *
See flash_main.cpp * - * - * todo: merge https://github.com/rusefi/rusefi/wiki/Dev-Tips into here - * * @section sec_fuel_injection Fuel Injection * * diff --git a/firmware/tunerstudio/rusefi.input b/firmware/tunerstudio/rusefi.input index 49b36c8833..4824e378e5 100644 --- a/firmware/tunerstudio/rusefi.input +++ b/firmware/tunerstudio/rusefi.input @@ -170,7 +170,7 @@ enable2ndByteCanID = false ; ; in order to add new TunerStudio gauge you need to chagne two places ; 1) add a line here in '[OutputChannels]' -; 2) in rusEFI firmware make a change to tunerstudio_outputs.h +; 2) in rusEFI firmware make a change to output_channels.txt ; [OutputChannels]