eFLL - A Fuzzy Library for Arduino and Embeded Systems

Leia este artigo em Português

Fuzzy Logic is an extension of traditional Boolean logic, using linguistic variables allows to express logical values ​​intermediate between FALSE and TRUE, describing with greater efficiency the uncertainty principle in the real world.

Fuzzy Systems are practical applications that employ Fuzzy Logic in its decisions making on the basis of linguistic variables and terms, the robotics and the electronic engineering has a large utility room.

Developed by Robotic Research Group (RRG) at the State University of Piauí (UESPI-Teresina) the eFLL (Embedded Fuzzy Logic Library) library is a versatile, lightweight and efficient option to work with Fuzzy Logic in embedded systems.

Please, report bugs and suggestions with comments or in the official code page on GitHub


How to install

Step 1: Go to the official project page on GitHub: eFLL

Step 2: Make a clone of the project using Git or download it Donwload on the button "Download as zip."

Step 3: Clone or unzip the files into Arduino libraries' folder:

Obs: Rename the folder from "eFLL-master" to "eFLL"

Ubuntu (/usr/share/arduino/libraries/) if installed via apt-get, if not, on Windows, Mac or Linux (where you downloaded the Arduino IDE, the Library folder is inside)

Ok! The library is ready to be used.

How to import

If the installation of the library has been successfully held,  to import the library is easy:

Step 1: Open your Arduino IDE, check out the tab on the top menu SKETCKS → LIBRARY  → Import eFLL

Características

Written in C++/C, uses only standard C language library "stdlib.h", so eFLL is a library designed not only to Arduino, but any Embedded System or not how have your commands written in C.

It has no explicit limitations on quantity of Fuzzy, Fuzzy Rules, Inputs or Outputs, these limited processing power and storage of each microcontroller

The library uses the process:

(MAX-MIN) and (Minimum Mamdani) for inference and composition and (CENTER OF AREA) to defuzzification in a continuous universe.

Tested with GTest for C, Google Inc.

Simple example:

Speed ​​control of a robotic,  entry: Frontal distance obstacle.

#include <FuzzyRule.h>
#include <FuzzyComposition.h>
#include <Fuzzy.h>
#include <FuzzyRuleConsequent.h>
#include <FuzzyOutput.h>
#include <FuzzyInput.h>
#include <FuzzyIO.h>
#include <FuzzySet.h>
#include <FuzzyRuleAntecedent.h>

// Step 1 -  Instantiating an object library
Fuzzy* fuzzy = new Fuzzy();

void setup(){
 Serial.begin(9600);

 // Step 2 - Creating a FuzzyInput distance
 FuzzyInput* distance = new FuzzyInput(1);// With its ID in param

 // Creating the FuzzySet to compond FuzzyInput distance
 FuzzySet* small = new FuzzySet(0, 20, 20, 40); // Small distance
 distance->addFuzzySet(small); // Add FuzzySet small to distance
 FuzzySet* safe = new FuzzySet(30, 50, 50, 70); // Safe distance
 distance->addFuzzySet(safe); // Add FuzzySet safe to distance
 FuzzySet* big = new FuzzySet(60, 80, 80, 80); // Big distance
 distance->addFuzzySet(big); // Add FuzzySet big to distance

 fuzzy->addFuzzyInput(distance); // Add FuzzyInput to Fuzzy object

 // Passo 3 - Creating FuzzyOutput velocity
 FuzzyOutput* velocity = new FuzzyOutput(1);// With its ID in param

 // Creating FuzzySet to compond FuzzyOutput velocity
 FuzzySet* slow = new FuzzySet(0, 10, 10, 20); // Slow velocity
 velocity->addFuzzySet(slow); // Add FuzzySet slow to velocity
 FuzzySet* average = new FuzzySet(10, 20, 30, 40); // Average velocity
 velocity->addFuzzySet(average); // Add FuzzySet average to velocity
 FuzzySet* fast = new FuzzySet(30, 40, 40, 50); // Fast velocity
 velocity->addFuzzySet(fast); // Add FuzzySet fast to velocity

 fuzzy->addFuzzyOutput(velocity); // Add FuzzyOutput to Fuzzy object

 //Passo 4 - Assembly the Fuzzy rules
 // FuzzyRule "IF distance = samll THEN velocity = slow"
 FuzzyRuleAntecedent* ifDistanceSmall = new FuzzyRuleAntecedent(); // Instantiating an Antecedent to expression
 ifDistanceSmall->joinSingle(small); // Adding corresponding FuzzySet to Antecedent object
 FuzzyRuleConsequent* thenVelocitySlow = new FuzzyRuleConsequent(); // Instantiating a Consequent to expression
 thenVelocitySlow->addOutput(slow);// Adding corresponding FuzzySet to Consequent object
 // Instantiating a FuzzyRule object
 FuzzyRule* fuzzyRule01 = new FuzzyRule(1, ifDistanceSmall, thenVelocitySlow); // Passing the Antecedent and the Consequent of expression
 
 fuzzy->addFuzzyRule(fuzzyRule01); // Adding FuzzyRule to Fuzzy object
 
 // FuzzyRule "IF distance = safe THEN velocity = normal"
 FuzzyRuleAntecedent* ifDistanceSafe = new FuzzyRuleAntecedent(); // Instantiating an Antecedent to expression
 ifDistanceSafe->joinSingle(safe); // Adding corresponding FuzzySet to Antecedent object
 FuzzyRuleConsequent* thenVelocityAverage = new FuzzyRuleConsequent(); // Instantiating a Consequent to expression
 thenVelocityAverage->addOutput(average); // Adding corresponding FuzzySet to Consequent object
 // Instantiating a FuzzyRule object
 FuzzyRule* fuzzyRule02 = new FuzzyRule(2, ifDistanceSafe, thenVelocityAverage); // Passing the Antecedent and the Consequent of expression
 
 fuzzy->addFuzzyRule(fuzzyRule02); // Adding FuzzyRule to Fuzzy object
 
 // FuzzyRule "IF distance = big THEN velocity = fast"
 FuzzyRuleAntecedent* ifDistanceBig = new FuzzyRuleAntecedent(); // Instantiating an Antecedent to expression
 ifDistanceBig->joinSingle(big); // Adding corresponding FuzzySet to Antecedent object
 FuzzyRuleConsequent* thenVelocityFast = new FuzzyRuleConsequent(); // Instantiating a Consequent to expression
 thenVelocityFast->addOutput(fast);// Adding corresponding FuzzySet to Consequent object
 // Instantiating a FuzzyRule object
 FuzzyRule* fuzzyRule03 = new FuzzyRule(3, ifDistanceBig, thenVelocityFast); // Passing the Antecedent and the Consequent of expression
 
 fuzzy->addFuzzyRule(fuzzyRule03); // Adding FuzzyRule to Fuzzy object
}

void loop(){
 float dist = getDistanceFromSonar(); 
 
// Step 5 - Report inputs value, passing its ID and value
fuzzy->setInput(1, dist); 
 // Step 6 - Exe the fuzzification
 fuzzy->fuzzify(); 
 // Step 7 - Exe the desfuzzyficação for each output, passing its ID
 float output = fuzzy->defuzzify(1);

 setRobotSpeed(output);

 delay(100);
}

Brief documentation

Fuzzy object - This object includes all the Fuzzy System, through it, you can manipulate the Fuzzy Sets, Linguistic Rules, inputs and outputs.

FuzzyInput object - This object groups all entries Fuzzy Sets that belongs to the same domain.

FuzzyOutput object - This object is similar to FuzzyInput, is used to group all output Fuzzy Sets thar belongs to the same domain.

FuzzySet object - This is one of the main objects of Fuzzy Library, with each set is possible to model the system in question. Currently the library supports triangular membership functions, trapezoidal and singleton, which are assembled based on points A, B, C and D, they are passed by parameter in its constructor FuzzySet(float a, float b, float c, float d) examples:

Triangular pertinence function:

FuzzySet* fs = FuzzySet(10, 20, 20, 30);

FuzzySet* fs = FuzzySet(10, 33, 33, 33);

FuzzySet* fs = FuzzySet(5, 5, 5, 30);

Trapezoidal pertinence function:

FuzzySet* fs = FuzzySet(10, 20, 30, 40);

FuzzySet* fs = FuzzySet(0, 0, 10, 20);

Any value below 10 will have pertinence = 1

FuzzySet* fs = FuzzySet(20, 30, 40, 40);

Any value above 30 will have pertinence = 1

Singleton pertinence function:

FuzzySet* fs = FuzzySet(20, 20, 20, 20);

FuzzyRule object - This object is used to mount the base rule of Fuzzy object, which contains one or more of this object. Instantiated with FuzzyRule fr = new FuzzyRule (ID, antecedent, consequent)

FuzzyRuleAntecedent object - This object is used to compound the object FuzzyRule, responsible for assembling the antecedent of the conditional expression of a FuzzyRule, examples:

"IF distance = small THEN velocity = slow"

FuzzyRuleAntecedent* ifDistanceSmall = new FuzzyRuleAntecedent(); ifDistanceSmall->joinSingle(small);

The method joinSingle(FuzzySet* fuzzySet) is used to build simple expressions IF/THEN. To compose more complex expressions there are other special methods.

"IF temperature = hot AND pressure = hight THEN rick = big"

FuzzyRuleAntecedent* ifTemperatureHotAndPressureHight = new FuzzyRuleAntecedent();
ifTemperatureHotAndPressureHight->joinWithAND(hot, hight); 

"IF temperature = hot OR pressure = hight THEN rick = big"

FuzzyRuleAntecedent* ifTemperatureHotAndPressureHight = new FuzzyRuleAntecedent();
ifTemperatureHotAndPressureHight->joinWithOR(hot, hight);

The methods joinWithAND(FuzzySet* fuzzySet1, FuzzySet* fuzzySet2) and joinWithOR(FuzzySet* fuzzySet1, FuzzySet* fuzzySet2) can make logical compositions between Fuzzy Sets. These methods also have more advanced variations that allow further enhance the expression, they are:

bool joinWithAND(FuzzySet* fuzzySet, FuzzyRuleAntecedent* fuzzyRuleAntecedent);
bool joinWithAND(FuzzyRuleAntecedent* fuzzyRuleAntecedent, FuzzySet* fuzzySet);
bool joinWithOR(FuzzySet* fuzzySet, FuzzyRuleAntecedent* fuzzyRuleAntecedent);
bool joinWithOR(FuzzyRuleAntecedent* fuzzyRuleAntecedent, FuzzySet* fuzzySet);
bool joinWithAND(FuzzyRuleAntecedent* fuzzyRuleAntecedent1, FuzzyRuleAntecedent* fuzzyRuleAntecedent2);
bool joinWithOR(FuzzyRuleAntecedent* fuzzyRuleAntecedent1, FuzzyRuleAntecedent* fuzzyRuleAntecedent2);

examples:

"IF (velocity = hight AND distance = small) OR fuel = low THEN velocity = small AND consumption = short"

FuzzyRuleAntecedent* speedHightAndDistanceSmall = new FuzzyRuleAntecedent();
speedHightAndDistanceSmall->joinWithAND(hight, small); 

FuzzyRuleAntecedent* fuelLow = new FuzzyRuleAntecedent();
fuelLow->joinSingle(low); 

// Este objeto FuzzyRuleAntecedente é que será usada para compor o objeto FuzzyRule 
FuzzyRuleAntecedent* ifSpeedHightAndDistanceSmallOrFuelLow = new FuzzyRuleAntecedent();
ifSpeedHightAndDistanceSmallOrFuelLow->joinWithOR(speedHightAndDistanceSmall, fuelLow); 

Using these methods, any expression can be mounted, FuzzyRuleAntecedent can be used to compose another object FuzzyRuleAntecedent, in many different ways. 
OBS:. in the previous example, the final antecedent was composed of  speedHightAndDistanceSmall and fuelLow objects, but the latter could be replaced without loss by the FuzzySet object low, since it is a simple expression, without any conditional operator:

FuzzyRuleAntecedent* speedHightAndDistanceSmall = new FuzzyRuleAntecedent();
speedHightAndDistanceSmall->joinWithAND(hight, small); 

// Este objeto FuzzyRuleAntecedente é que será usada para compor o objeto FuzzyRule 
FuzzyRuleAntecedent* ifSpeedHightAndDistanceSmallOrFuelLow = new FuzzyRuleAntecedent();
ifSpeedHightAndDistanceSmallOrFuelLow->joinWithOR(speedHightAndDistanceSmall, low); 

FuzzyRuleConsequente object - This object is used to render the object FuzzyRule, responsible for assembling the output expression of a FuzzyRule, examples:

"IF disctance = small THEN velocity = slow"

FuzzyRuleConsequent* thenSpeedSlow = new FuzzyRuleConsequent(); 
thenSpeedSlow->addOutput(slow);

What would result in an FuzzyRule object like:

FuzzyRule* fuzzyRule = new FuzzyRule(2, ifDistanceSmall, thenSpeedSlow);

"IF (velocity = hight AND distance = small) OR fuel = low THEN velocity = small AND consumption = short"

FuzzyRuleConsequent* thenSpeedSmallAndFeedTine = new FuzzyRuleConsequent(); thenSpeedSmallAndFeedSmall->addOutput(small);

thenSpeedSmallAndFeedSmall->addOutput(tine);  

For the object FuzzyRuleConsequent entire expression is mounted using the method addOutput(FuzzySet* fuzzySet);

What would result in an FuzzyRule object like:

FuzzyRule* fuzzyRule = new FuzzyRule(2, ifSpeedHightAndDistanceSmallOrFuelLow, thenSpeedSmallAndFeedTine);

After assembling an FuzzyRule object, use the method addFuzzyRule(FuzzyRule* fuzzyRule); to add it to Fuzzy object base rule, repeat the same process for all the rules.

Tip

These are all eFLL library objects that are used in the process. The next step, generally interactive is handled by three methods of the Fuzzy Class first:

bool setInput(int id, float value);

It is used to pass the Crispe input value to the system note that the first parameter is the FuzzyInput object' ID which parameter value is intended.

bool fuzzify();

It is used to start the fuzzification process, composition and inference.

And finally:

float defuzzify(int id);

It is used to finalize the fuzzification process, notice that the param ID belongs to FuzzyOutput object which you want to get the defuzzification value.

Hint: Sometimes is necessary to know the pertinence with which some or each fuzzy set was activated. To do this, use the method float getPertinence();  of FuzzySet Class, eg:

FuzzySet* hot = new FuzzySet(30, 50, 50, 70);
...
... // After fuzzification with ->fuzzyfy();
...
float pertinenceOfHot = hot->getPertinence();

Or whether a particular rule was fired, use the method bool isFiredRule(int ruleId); of Fuzzy object.

FuzzyRule* fuzzyRule = new FuzzyRule(2, ifDistanceSmall, thenSpeedSlow);
...
... // After fuzzification with ->fuzzyfy();
...
bool wasTheRulleFired = fuzzy->isFiredRule(2);

Advanced example:

#include <FuzzyRule.h>
#include <FuzzyComposition.h>
#include <Fuzzy.h>
#include <FuzzyRuleConsequent.h>
#include <FuzzyOutput.h>
#include <FuzzyInput.h>
#include <FuzzyIO.h>
#include <FuzzySet.h>
#include <FuzzyRuleAntecedent.h>

// Instantiating an object of library
Fuzzy* fuzzy = new Fuzzy();

FuzzySet* close = new FuzzySet(0, 20, 20, 40);
FuzzySet* safe = new FuzzySet(30, 50, 50, 70);
FuzzySet* distante = new FuzzySet(60, 80, 100, 100);

FuzzySet* stoped = new FuzzySet(0, 0, 0, 0);
FuzzySet* slow = new FuzzySet(1, 10, 10, 20);
FuzzySet* normal = new FuzzySet(15, 30, 30, 50);
FuzzySet* quick = new FuzzySet(45, 60, 70, 70);

FuzzySet* cold = new FuzzySet(-30, -30, -20, -10);
FuzzySet* good = new FuzzySet(-15, 0, 0, 15);
FuzzySet* hot = new FuzzySet(10, 20, 30, 30);

void setup(){
  Serial.begin(9600);
  
  // FuzzyInput
  FuzzyInput* distance = new FuzzyInput(1);
  distance->addFuzzySet(close);
  distance->addFuzzySet(safe);
  distance->addFuzzySet(distante);

  fuzzy->addFuzzyInput(distance);

  // FuzzyInput
  FuzzyInput* inputSpeed = new FuzzyInput(2);
  inputSpeed->addFuzzySet(stoped);
  inputSpeed->addFuzzySet(slow);
  inputSpeed->addFuzzySet(normal);
  inputSpeed->addFuzzySet(quick);

  fuzzy->addFuzzyInput(inputSpeed);

  // FuzzyInput
  FuzzyInput* temperature = new FuzzyInput(3);
  temperature->addFuzzySet(cold);
  temperature->addFuzzySet(good);
  temperature->addFuzzySet(hot);

  fuzzy->addFuzzyInput(temperature);

  // FuzzyOutput
  FuzzyOutput* risk = new FuzzyOutput(1);

  FuzzySet* minimum = new FuzzySet(0, 20, 20, 40);
  risk->addFuzzySet(minimum);
  FuzzySet* average = new FuzzySet(30, 50, 50, 70);
  risk->addFuzzySet(average);
  FuzzySet* maximum = new FuzzySet(60, 80, 80, 100);
  risk->addFuzzySet(maximum);

  fuzzy->addFuzzyOutput(risk);

  // FuzzyOutput
  // adding speed as output too
  FuzzyOutput* outputSpeed = new FuzzyOutput(2);

  FuzzySet* stopedOut = new FuzzySet(0, 0, 0, 0);
  outputSpeed->addFuzzySet(stopedOut);
  FuzzySet* slowOut = new FuzzySet(1, 10, 10, 20);
  outputSpeed->addFuzzySet(slowOut);
  FuzzySet* normalOut = new FuzzySet(15, 30, 30, 50);
  outputSpeed->addFuzzySet(normalOut);
  FuzzySet* quickOut = new FuzzySet(45, 60, 70, 70);
  outputSpeed->addFuzzySet(quickOut);

  fuzzy->addFuzzyOutput(outputSpeed);

  // Building FuzzyRule
  FuzzyRuleAntecedent* distanceCloseAndSpeedQuick = new FuzzyRuleAntecedent();
  distanceCloseAndSpeedQuick->joinWithAND(close, quick);
  FuzzyRuleAntecedent* temperatureCold = new FuzzyRuleAntecedent();
  temperatureCold->joinSingle(cold);
  FuzzyRuleAntecedent* ifDistanceCloseAndSpeedQuickOrTemperatureCold = new FuzzyRuleAntecedent();
  ifDistanceCloseAndSpeedQuickOrTemperatureCold->joinWithOR(distanceCloseAndSpeedQuick, temperatureCold);

  FuzzyRuleConsequent* thenRisMaximumAndSpeedSlow = new FuzzyRuleConsequent();
  thenRisMaximumAndSpeedSlow->addOutput(maximum);
  thenRisMaximumAndSpeedSlow->addOutput(slowOut);

  FuzzyRule* fuzzyRule1 = new FuzzyRule(1, ifDistanceCloseAndSpeedQuickOrTemperatureCold, thenRisMaximumAndSpeedSlow);
  fuzzy->addFuzzyRule(fuzzyRule1);

  // Building FuzzyRule
  FuzzyRuleAntecedent* distanceSafeAndSpeedNormal = new FuzzyRuleAntecedent();
  distanceSafeAndSpeedNormal->joinWithAND(safe, normal);
  FuzzyRuleAntecedent* ifDistanceSafeAndSpeedNormalOrTemperatureGood = new FuzzyRuleAntecedent();
  ifDistanceSafeAndSpeedNormalOrTemperatureGood->joinWithOR(distanceSafeAndSpeedNormal, good);

  FuzzyRuleConsequent* thenRiskAverageAndSpeedNormal = new FuzzyRuleConsequent();
  thenRiskAverageAndSpeedNormal->addOutput(average);
  thenRiskAverageAndSpeedNormal->addOutput(normalOut);

  FuzzyRule* fuzzyRule2 = new FuzzyRule(2, ifDistanceSafeAndSpeedNormalOrTemperatureGood, thenRiskAverageAndSpeedNormal);
  fuzzy->addFuzzyRule(fuzzyRule2);

  // Building FuzzyRule
  FuzzyRuleAntecedent* distanceDistanteAndSpeedSlow = new FuzzyRuleAntecedent();
  distanceDistanteAndSpeedSlow->joinWithAND(distante, slow);
  FuzzyRuleAntecedent* ifDistanceDistanteAndSpeedSlowOrTemperatureHot = new FuzzyRuleAntecedent();
  ifDistanceDistanteAndSpeedSlowOrTemperatureHot->joinWithOR(distanceDistanteAndSpeedSlow, hot);

  FuzzyRuleConsequent* thenRiskMinimumSpeedQuick = new FuzzyRuleConsequent();
  thenRiskMinimumSpeedQuick->addOutput(minimum);
  thenRiskMinimumSpeedQuick->addOutput(quickOut);

  FuzzyRule* fuzzyRule3 = new FuzzyRule(3, ifDistanceDistanteAndSpeedSlowOrTemperatureHot, thenRiskMinimumSpeedQuick);
  fuzzy->addFuzzyRule(fuzzyRule3);
}

void loop(){
  fuzzy->setInput(1, 10);
  fuzzy->setInput(2, 30);
  fuzzy->setInput(3, -15);

  fuzzy->fuzzify();
  
  Serial.print("Distance: ");
  Serial.print(close->getPertinence());
  Serial.print(", ");
  Serial.print(safe->getPertinence());
  Serial.print(", ");
  Serial.println(distante->getPertinence());
  
  Serial.print("Speed: ");
  Serial.print(stoped->getPertinence());
  Serial.print(", ");
  Serial.print(slow->getPertinence());
  Serial.print(", ");
  Serial.print(normal->getPertinence());
  Serial.print(", ");
  Serial.println(quick->getPertinence());
  
  Serial.print("Temperature: ");
  Serial.print(cold->getPertinence());
  Serial.print(", ");
  Serial.print(good->getPertinence());
  Serial.print(", ");
  Serial.println(hot->getPertinence());

  float output1 = fuzzy->defuzzify(1);
  float output2 = fuzzy->defuzzify(2);
  
  Serial.print("Risk output: ");
  Serial.print(output1);
  Serial.print(", Speed output: ");
  Serial.println(output2);

  delay(100000);
}

Another example: https://gist.github.com/4110773

 Biblioteca eFLL é licenciada sob uma Licença Creative Commons Atribuição-SemDerivados 3.0 Não Adaptada.

Baseado no trabalho em http://github.com/zerokol/eFLL.

Perssões além do escopo dessa licença podem estar disponível em http://zerokol.com.