Aprender

Arduino strtok: dividir texto e interpretar comandos seriais

Ou veja todas as aulas.

  • 526componentes na bancada
  • 46placas rodando agora
  • 1.00xtempo real, em todas as placas
Arduino Uno: eco do que o monitor serial enviaao vivo0.000 s 0.00x
Clique para abrir no editor
Digite uma palavra e aperte Enter: cada byte volta em sua própria linha, o newline por último.

strtok() divide um array de char em pedaços nos caracteres que você indicar, como vírgulas ou espaços. A primeira chamada recebe o array, cada chamada seguinte recebe NULL e continua de onde a última parou, e ela retorna NULL quando não sobra nada. Funciona com texto C puro em vez de uma String, então usa pouca memória e serve para as linhas curtas que um sensor ou o monitor serial envia.

O circuito acima é um Uno que faz eco do que você digita, um byte por vez. Ao digitar "on" e Enter, ele imprimiu "you typed: o (0x6F)", "you typed: n (0x6E)" e "you typed: <newline>". Os bytes chegam um a um, então um sketch primeiro os reúne em uma linha e só depois a divide.

Abaixo você vê como dividir valores separados por vírgula em números, o que strtok faz com o seu array, por que uma String precisa de uma cópia, um interpretador de comandos que acende LEDs, e strtok_r para uma divisão dentro de outra divisão. Para dividir uma String com indexOf() e substring() em vez disso, veja a página da String.

Quer a versão passo a passo? A aula "Recebendo comandos" percorre isso com checkpoints.

Abrir a aula

Dividir valores separados por vírgula em um array

Chame strtok(line, ",") uma vez para o primeiro pedaço, depois strtok(NULL, ",") em um laço até retornar NULL, convertendo cada pedaço com atof() para decimais ou atoi() para números inteiros. O sketch abaixo imprimiu "3 values", depois "21.50", "48.00" e "1013.00".

Pare no tamanho do seu array, como o count < 3 faz: uma linha com mais vírgulas do que você esperava não pode escrever além do fim.

The last line shows what strtok leaves behind. It printed "line is now: 21.5". strtok writes a zero over each comma it finds, so the array now ends after the first piece. Copy the line first if you need it again.

Três números de uma linha
void setup() {
  Serial.begin(9600);
  char line[] = "21.5,48,1013";
  float values[3];
  int count = 0;

  char *piece = strtok(line, ",");
  while (piece != NULL && count < 3) {
    values[count] = atof(piece);
    count++;
    piece = strtok(NULL, ",");
  }

  Serial.print(count);
  Serial.println(" values");
  for (int i = 0; i < count; i++) {
    Serial.println(values[i]);
  }
  Serial.print("line is now: ");
  Serial.println(line);
}

void loop() {
}

Abrir este sketch no editorSó o código: o editor posiciona a placa e os componentes que ele consegue ler do sketch.

Campos vazios desaparecem

strtok trata uma sequência de vírgulas como uma só, então um campo vazio é pulado em vez de retornado como vazio. O mesmo sketch com "5,,7" imprimiu "2 values", 5.00 e 7.00: o 7 foi para a segunda posição. Quando um campo pode ficar em branco, confira a contagem, ou envie um 0 em vez de nada.

strtok precisa de um array de char, não de uma String

strtok changes the text it splits, so it takes a char *. Giving it a String’s text with strtok(line.c_str(), ",") stopped the build with no matching function for call to 'strtok', and the note says 1st argument ('const char *') would lose const qualifier: c_str() is read only. The Arduino IDE’s GCC says invalid conversion from 'const char*' to 'char*'.

Copie a String para um array de char primeiro com toCharArray(). O sketch abaixo imprimiu "21.5" e "48". Uma string entre aspas escrita direto na chamada, strtok("21.5,48", ","), só recebeu um aviso, ISO C++11 does not allow conversion from string literal to 'char *', e o do GCC é ISO C++ forbids converting a string constant to 'char*'. Rodou aqui e imprimiu 21.5, mas não conte com isso: texto entre aspas deve permanecer como está, e strtok escreve nele.

Uma String copiada para um array de char
void setup() {
  Serial.begin(9600);
  String line = "21.5,48";
  char buf[32];
  line.toCharArray(buf, sizeof(buf));
  char *piece = strtok(buf, ",");
  while (piece != NULL) {
    Serial.println(piece);
    piece = strtok(NULL, ",");
  }
}

void loop() {
}

Abrir este sketch no editorSó o código: o editor posiciona a placa e os componentes que ele consegue ler do sketch.

Um interpretador de comandos seriais

O sketch abaixo reúne bytes em um buffer de 32 bytes até um newline, depois divide a linha nos espaços em um comando e dois argumentos e compara o comando com strcmp(). Ele entende "led 13 on", "led 12 off" e "blink 11 3". Qualquer outra coisa também recebe resposta, então um erro de digitação nunca fica em silêncio.

Digitamos cinco linhas: led 13 on, led 12 on, led 13 off, blink 11 3 e hello. Imprimiu "pin 13 on", "pin 12 on", "pin 13 off", "blinked 3 times" e "unknown: hello", e deixou o LED no pino 12 aceso. A verificação len < sizeof(buf) - 1 descarta tudo que passa de 31 caracteres em vez de escrever além do buffer, e o teste do \r faz funcionar com qualquer final de linha que o monitor enviar. Para aceitar vírgulas além de espaços entre as palavras, passe " ," como separadores do strtok em vez de " ".

Comandos para três LEDs
char buf[32];
byte len = 0;

void setup() {
  Serial.begin(9600);
  pinMode(13, OUTPUT);
  pinMode(12, OUTPUT);
  pinMode(11, OUTPUT);
  Serial.println("ready");
}

void runCommand(char *line) {
  char *cmd = strtok(line, " ");
  char *arg1 = strtok(NULL, " ");
  char *arg2 = strtok(NULL, " ");
  if (cmd == NULL) return;

  if (strcmp(cmd, "led") == 0 && arg1 && arg2) {
    int pin = atoi(arg1);
    digitalWrite(pin, strcmp(arg2, "on") == 0 ? HIGH : LOW);
    Serial.print("pin ");
    Serial.print(pin);
    Serial.print(" ");
    Serial.println(arg2);
  } else if (strcmp(cmd, "blink") == 0 && arg1 && arg2) {
    int pin = atoi(arg1);
    int times = atoi(arg2);
    for (int i = 0; i < times; i++) {
      digitalWrite(pin, HIGH);
      delay(100);
      digitalWrite(pin, LOW);
      delay(100);
    }
    Serial.print("blinked ");
    Serial.print(times);
    Serial.println(" times");
  } else {
    Serial.print("unknown: ");
    Serial.println(cmd);
  }
}

void loop() {
  while (Serial.available() > 0) {
    char c = Serial.read();
    if (c == '\r') continue;
    if (c == '\n') {
      buf[len] = '\0';
      runCommand(buf);
      len = 0;
    } else if (len < sizeof(buf) - 1) {
      buf[len++] = c;
    }
  }
}

Abrir este sketch no editorSó o código: o editor posiciona a placa e os componentes que ele consegue ler do sketch.

Uma divisão dentro de outra: strtok_r

strtok guarda seu lugar em uma variável oculta, então só consegue trabalhar em uma linha por vez. Dividir "temp=21;hum=48;lux=310" nos pontos e vírgula, e cada par no sinal de igual também com strtok, imprimiu "temp -> 21" e parou: as chamadas internas perderam o lugar da externa.

strtok_r recebe o lugar como terceiro argumento, então cada nível mantém o seu. A versão abaixo imprimiu "temp -> 21", "hum -> 48" e "lux -> 310". Use strtok_r sempre que uma função que divide texto puder ser chamada de dentro de outra divisão.

Pares de chave e valor com strtok_r
void setup() {
  Serial.begin(9600);
  char line[] = "temp=21;hum=48;lux=310";
  char *outer;
  char *pair = strtok_r(line, ";", &outer);
  while (pair != NULL) {
    char *inner;
    char *key = strtok_r(pair, "=", &inner);
    char *value = strtok_r(NULL, "=", &inner);
    Serial.print(key);
    Serial.print(" -> ");
    Serial.println(atoi(value));
    pair = strtok_r(NULL, ";", &outer);
  }
}

void loop() {
}

Abrir este sketch no editorSó o código: o editor posiciona a placa e os componentes que ele consegue ler do sketch.

Abra este circuito no editor. Arduino Uno: eco do que o monitor serial envia, ligado como roda no topo desta página. Troque um componente ou um valor e rode de novo.

Perguntas

Como funciona o strtok no Arduino?

The first call, strtok(line, ","), returns the first piece of a char array; each later call, strtok(NULL, ","), returns the next, and NULL means there are no more. It replaces each separator in the array with a zero as it goes.

Posso usar strtok com uma String?

Não diretamente: c_str() é somente leitura e strtok escreve no texto, então a compilação para. Copie a String para um array de char com toCharArray() e divida esse array.

Por que o strtok pula meu campo vazio?

Ele trata dois separadores seguidos como um só, então "5,,7" dá dois pedaços, não três. Confira quantos pedaços voltaram, ou envie um 0 para um valor ausente.

Como faço para interpretar comandos do monitor serial?

Collect bytes into a char array until a newline, end it with a zero, split it at spaces with strtok, and compare the first piece with strcmp(). The parser on this page does it for LED commands.

Qual é a diferença entre strtok e strtok_r?

strtok guarda seu lugar em uma variável oculta, então duas divisões ao mesmo tempo interferem entre si. strtok_r recebe o lugar como argumento, então uma divisão dentro de outra funciona.

Monte isto de verdade

Abra o editor, mude um valor e veja o número mudar junto. Nada para instalar, e não precisa de conta.