From aa3f18e0458e2cbc07020cf20da5c74177d9b04e Mon Sep 17 00:00:00 2001 From: Falon <47285315+falOn-Dev@users.noreply.github.com> Date: Thu, 5 Sep 2024 14:58:09 -0400 Subject: [PATCH 01/19] Create check_codeblock_coverage.py --- scripts/check_codeblock_coverage.py | 57 +++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 scripts/check_codeblock_coverage.py diff --git a/scripts/check_codeblock_coverage.py b/scripts/check_codeblock_coverage.py new file mode 100644 index 0000000000..7a5ec54bc2 --- /dev/null +++ b/scripts/check_codeblock_coverage.py @@ -0,0 +1,57 @@ +import sys, os +from dataclasses import dataclass + +@dataclass +class CodeBlock: + block: str + start: int + file: str + + +def get_all_rst_files(dir): + files = [] + for root, dirs, filenames in os.walk(dir): + for filename in filenames: + if filename.endswith('.rst'): + files.append(os.path.join(root, filename)) + + return files + +def get_blocks_from_rst_file(file): + blocks = [] + with(open(file, 'r')) as f: + block_text = '' + found_block = False + block_start = None + for linenum, line in enumerate(f): + if line.startswith(".. tab-set-code::"): + found_block = True + block_text += line + block_start = linenum + elif found_block: + if line.startswith(' ') or line.startswith('\t'): + block_text += line + else: + blocks.append(CodeBlock(block=block_text, start=block_start, file=file)) + block_text = '' + block_start = None + found_block = False + return blocks + +def main(): + dir = sys.argv[1] + files = get_all_rst_files(dir=dir) + for file in files: + blocks = get_blocks_from_rst_file(file) + if len(blocks) == 0: continue + else: + with(open("output.txt", 'w')) as f: + for block in blocks: + f.write(f"File: {block.file}\n") + f.write(f"Block: {block.block}\n") + f.write(f"Start: {block.start}\n") + f.write("\n") + break + +if __name__ == '__main__': + main() \ No newline at end of file From e4e0939789d4ce697c6dd0b567adaecd461924f0 Mon Sep 17 00:00:00 2001 From: Europa Date: Thu, 5 Sep 2024 16:52:16 -0400 Subject: [PATCH 02/19] Update check_codeblock_coverage.py --- scripts/check_codeblock_coverage.py | 53 ++++++++++++++++++++--------- 1 file changed, 36 insertions(+), 17 deletions(-) diff --git a/scripts/check_codeblock_coverage.py b/scripts/check_codeblock_coverage.py index 7a5ec54bc2..6cc864f56d 100644 --- a/scripts/check_codeblock_coverage.py +++ b/scripts/check_codeblock_coverage.py @@ -1,11 +1,13 @@ -import sys, os +import sys, os, re from dataclasses import dataclass @dataclass class CodeBlock: - block: str start: int file: str + langs: list[str] + block: str + def get_all_rst_files(dir): @@ -17,41 +19,58 @@ def get_all_rst_files(dir): return files -def get_blocks_from_rst_file(file): +def is_codeblock(line: str): + return line.startswith(".. tab-set-code::") or line.startswith(".. tab-set::") + +def get_blocks_from_rst_file(file: str): + lang_regex = re.compile("(java|python|cpp)") blocks = [] - with(open(file, 'r')) as f: + with(open(file, 'r', encoding='utf8')) as f: block_text = '' found_block = False block_start = None - for linenum, line in enumerate(f): - if line.startswith(".. tab-set-code::"): + langs = [] + for index, line in enumerate(f): + if is_codeblock(line): found_block = True block_text += line - block_start = linenum + block_start = index + 1 elif found_block: if line.startswith(' ') or line.startswith('\t'): + lang = re.search("(`{3}|:language: )(java|python|cpp|c\+\+)", line) + if(lang is not None): + langs.append(lang.group(2)) block_text += line else: - blocks.append(CodeBlock(block=block_text, start=block_start, file=file)) + if langs != []: + blocks.append( + CodeBlock( + block=block_text, + start=block_start, + file=file, + langs=langs + ) + ) + block_text = '' block_start = None found_block = False return blocks def main(): - dir = sys.argv[1] + # dir = sys.argv[1] + dir = "source" files = get_all_rst_files(dir=dir) + blocks = [] for file in files: - blocks = get_blocks_from_rst_file(file) - if len(blocks) == 0: continue + file_blocks = get_blocks_from_rst_file(file) + if len(file_blocks) == 0: + continue else: - with(open("output.txt", 'w')) as f: + blocks.extend(file_blocks) + with(open("output.txt", 'w')) as f: for block in blocks: - f.write(f"File: {block.file}\n") - f.write(f"Block: {block.block}\n") - f.write(f"Start: {block.start}\n") - f.write("\n") - break + f.write(f"Block: {block}\n") if __name__ == '__main__': main() \ No newline at end of file From be66f29d6118e34eb44e86c9c08a7069d97501f1 Mon Sep 17 00:00:00 2001 From: Falon <47285315+falOn-Dev@users.noreply.github.com> Date: Thu, 5 Sep 2024 17:07:36 -0400 Subject: [PATCH 03/19] Update check_codeblock_coverage.py --- scripts/check_codeblock_coverage.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/scripts/check_codeblock_coverage.py b/scripts/check_codeblock_coverage.py index 6cc864f56d..4206f8d170 100644 --- a/scripts/check_codeblock_coverage.py +++ b/scripts/check_codeblock_coverage.py @@ -37,7 +37,7 @@ def get_blocks_from_rst_file(file: str): block_start = index + 1 elif found_block: if line.startswith(' ') or line.startswith('\t'): - lang = re.search("(`{3}|:language: )(java|python|cpp|c\+\+)", line) + lang = re.search("(`{3}|:language: )(java|python|cpp|c\\+\\+)", line) if(lang is not None): langs.append(lang.group(2)) block_text += line @@ -55,6 +55,7 @@ def get_blocks_from_rst_file(file: str): block_text = '' block_start = None found_block = False + langs = [] return blocks def main(): From 99a21178c9170501dedc1a4161c3047e4bed2ae5 Mon Sep 17 00:00:00 2001 From: Falon <47285315+falOn-Dev@users.noreply.github.com> Date: Thu, 5 Sep 2024 17:50:23 -0400 Subject: [PATCH 04/19] Working version 1 --- scripts/check_codeblock_coverage.py | 72 ++++++++++++++++++----------- 1 file changed, 45 insertions(+), 27 deletions(-) diff --git a/scripts/check_codeblock_coverage.py b/scripts/check_codeblock_coverage.py index 4206f8d170..cdaa26e074 100644 --- a/scripts/check_codeblock_coverage.py +++ b/scripts/check_codeblock_coverage.py @@ -1,4 +1,4 @@ -import sys, os, re +import sys, os, re, argparse from dataclasses import dataclass @dataclass @@ -6,7 +6,6 @@ class CodeBlock: start: int file: str langs: list[str] - block: str @@ -23,45 +22,64 @@ def is_codeblock(line: str): return line.startswith(".. tab-set-code::") or line.startswith(".. tab-set::") def get_blocks_from_rst_file(file: str): - lang_regex = re.compile("(java|python|cpp)") blocks = [] with(open(file, 'r', encoding='utf8')) as f: - block_text = '' - found_block = False block_start = None langs = [] for index, line in enumerate(f): if is_codeblock(line): - found_block = True - block_text += line - block_start = index + 1 - elif found_block: - if line.startswith(' ') or line.startswith('\t'): - lang = re.search("(`{3}|:language: )(java|python|cpp|c\\+\\+)", line) - if(lang is not None): - langs.append(lang.group(2)) - block_text += line - else: - if langs != []: + if langs != []: blocks.append( CodeBlock( - block=block_text, start=block_start, file=file, langs=langs ) ) - block_text = '' - block_start = None - found_block = False - langs = [] + block_start = index + 1 + langs = [] + else: + if line.startswith(' ') or line.startswith('\t'): + lang = re.search("(`{3}|:language: )(java|python|c\\+\\+)", line.lower()) + if(lang is not None): + langs.append(lang.group(2)) return blocks +def generate_report(blocks: list[CodeBlock], langs: list[str], wordy: bool): + stream = sys.stdout + if wordy: + stream = open("output.txt", "w") + + blocks_count = len(blocks) + langs_coverage = {lang: 0 for lang in langs} + for block in blocks: + for lang in langs: + if lang in block.langs: + langs_coverage[lang] += 1 + print(f"Total code blocks: {blocks_count}", file=stream) + for lang, coverage in langs_coverage.items(): + print(f"{lang} coverage: {coverage}/{blocks_count} ({coverage/blocks_count*100:.2f}%)", file=stream) + + if wordy: + print("\n\nMissing code blocks:", file=stream) + for block in blocks: + missing_langs = [lang for lang in langs if lang not in block.langs] + if missing_langs: + print(f"File: {block.file}, Line: {block.start}", file=stream) + print(f"Missing languages: {missing_langs}", file=stream) + + stream.close() + def main(): - # dir = sys.argv[1] - dir = "source" - files = get_all_rst_files(dir=dir) + parser = argparse.ArgumentParser(description='Check code block coverage in FRC docs') + parser.add_argument('--dir', type=str, help='Directory to search for rst files') + parser.add_argument('--wordy', action='store_true', help='Outputs which code blocks are missing languages') + + args = parser.parse_args() + print(args.wordy) + + files = get_all_rst_files(dir=args.dir) blocks = [] for file in files: file_blocks = get_blocks_from_rst_file(file) @@ -69,9 +87,9 @@ def main(): continue else: blocks.extend(file_blocks) - with(open("output.txt", 'w')) as f: - for block in blocks: - f.write(f"Block: {block}\n") + generate_report(blocks=blocks, langs=["java", "python", "c++"], wordy=args.wordy) + + if __name__ == '__main__': main() \ No newline at end of file From 5f4a3b7b65b57d8b108f250807d49c0ab3f4c716 Mon Sep 17 00:00:00 2001 From: Falon <47285315+falOn-Dev@users.noreply.github.com> Date: Thu, 5 Sep 2024 17:54:49 -0400 Subject: [PATCH 05/19] Add in ability to set output dir and which langs to check --- scripts/check_codeblock_coverage.py | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/scripts/check_codeblock_coverage.py b/scripts/check_codeblock_coverage.py index cdaa26e074..1a00a19c3c 100644 --- a/scripts/check_codeblock_coverage.py +++ b/scripts/check_codeblock_coverage.py @@ -46,10 +46,10 @@ def get_blocks_from_rst_file(file: str): langs.append(lang.group(2)) return blocks -def generate_report(blocks: list[CodeBlock], langs: list[str], wordy: bool): +def generate_report(blocks: list[CodeBlock], langs: list[str], wordy: bool, output: str): stream = sys.stdout if wordy: - stream = open("output.txt", "w") + stream = open(output, "w") blocks_count = len(blocks) langs_coverage = {lang: 0 for lang in langs} @@ -75,6 +75,8 @@ def main(): parser = argparse.ArgumentParser(description='Check code block coverage in FRC docs') parser.add_argument('--dir', type=str, help='Directory to search for rst files') parser.add_argument('--wordy', action='store_true', help='Outputs which code blocks are missing languages') + parser.add_argument('--output', type=str, default='output.txt', help='Output file for missing code blocks') + parser.add_argument('--langs', nargs='+', default=["java", "python", "c++"], help='Languages to check for') args = parser.parse_args() print(args.wordy) @@ -87,7 +89,7 @@ def main(): continue else: blocks.extend(file_blocks) - generate_report(blocks=blocks, langs=["java", "python", "c++"], wordy=args.wordy) + generate_report(blocks=blocks, langs=args.langs, wordy=args.wordy, output=args.output) From 25e3b5bbf6dd2395790c86b28c74b95f43392a31 Mon Sep 17 00:00:00 2001 From: Falon <47285315+falOn-Dev@users.noreply.github.com> Date: Thu, 5 Sep 2024 17:55:33 -0400 Subject: [PATCH 06/19] Formatting --- scripts/check_codeblock_coverage.py | 76 +++++++++++++++++++---------- 1 file changed, 49 insertions(+), 27 deletions(-) diff --git a/scripts/check_codeblock_coverage.py b/scripts/check_codeblock_coverage.py index 1a00a19c3c..0c583d86c3 100644 --- a/scripts/check_codeblock_coverage.py +++ b/scripts/check_codeblock_coverage.py @@ -1,6 +1,7 @@ import sys, os, re, argparse from dataclasses import dataclass + @dataclass class CodeBlock: start: int @@ -8,45 +9,45 @@ class CodeBlock: langs: list[str] - def get_all_rst_files(dir): files = [] for root, dirs, filenames in os.walk(dir): for filename in filenames: - if filename.endswith('.rst'): + if filename.endswith(".rst"): files.append(os.path.join(root, filename)) return files + def is_codeblock(line: str): return line.startswith(".. tab-set-code::") or line.startswith(".. tab-set::") + def get_blocks_from_rst_file(file: str): blocks = [] - with(open(file, 'r', encoding='utf8')) as f: + with (open(file, "r", encoding="utf8")) as f: block_start = None langs = [] for index, line in enumerate(f): if is_codeblock(line): - if langs != []: - blocks.append( - CodeBlock( - start=block_start, - file=file, - langs=langs - ) - ) + if langs != []: + blocks.append(CodeBlock(start=block_start, file=file, langs=langs)) block_start = index + 1 langs = [] else: - if line.startswith(' ') or line.startswith('\t'): - lang = re.search("(`{3}|:language: )(java|python|c\\+\\+)", line.lower()) - if(lang is not None): + if line.startswith(" ") or line.startswith("\t"): + lang = re.search( + "(`{3}|:language: )(java|python|c\\+\\+)", line.lower() + ) + if lang is not None: langs.append(lang.group(2)) return blocks -def generate_report(blocks: list[CodeBlock], langs: list[str], wordy: bool, output: str): + +def generate_report( + blocks: list[CodeBlock], langs: list[str], wordy: bool, output: str +): stream = sys.stdout if wordy: stream = open(output, "w") @@ -59,7 +60,10 @@ def generate_report(blocks: list[CodeBlock], langs: list[str], wordy: bool, outp langs_coverage[lang] += 1 print(f"Total code blocks: {blocks_count}", file=stream) for lang, coverage in langs_coverage.items(): - print(f"{lang} coverage: {coverage}/{blocks_count} ({coverage/blocks_count*100:.2f}%)", file=stream) + print( + f"{lang} coverage: {coverage}/{blocks_count} ({coverage/blocks_count*100:.2f}%)", + file=stream, + ) if wordy: print("\n\nMissing code blocks:", file=stream) @@ -71,12 +75,29 @@ def generate_report(blocks: list[CodeBlock], langs: list[str], wordy: bool, outp stream.close() + def main(): - parser = argparse.ArgumentParser(description='Check code block coverage in FRC docs') - parser.add_argument('--dir', type=str, help='Directory to search for rst files') - parser.add_argument('--wordy', action='store_true', help='Outputs which code blocks are missing languages') - parser.add_argument('--output', type=str, default='output.txt', help='Output file for missing code blocks') - parser.add_argument('--langs', nargs='+', default=["java", "python", "c++"], help='Languages to check for') + parser = argparse.ArgumentParser( + description="Check code block coverage in FRC docs" + ) + parser.add_argument("--dir", type=str, help="Directory to search for rst files") + parser.add_argument( + "--wordy", + action="store_true", + help="Outputs which code blocks are missing languages", + ) + parser.add_argument( + "--output", + type=str, + default="output.txt", + help="Output file for missing code blocks", + ) + parser.add_argument( + "--langs", + nargs="+", + default=["java", "python", "c++"], + help="Languages to check for", + ) args = parser.parse_args() print(args.wordy) @@ -85,13 +106,14 @@ def main(): blocks = [] for file in files: file_blocks = get_blocks_from_rst_file(file) - if len(file_blocks) == 0: + if len(file_blocks) == 0: continue - else: + else: blocks.extend(file_blocks) - generate_report(blocks=blocks, langs=args.langs, wordy=args.wordy, output=args.output) - + generate_report( + blocks=blocks, langs=args.langs, wordy=args.wordy, output=args.output + ) -if __name__ == '__main__': - main() \ No newline at end of file +if __name__ == "__main__": + main() From 5f3d04ab6cfdefd4322dc0810f7af8f96dc69768 Mon Sep 17 00:00:00 2001 From: Falon <47285315+falOn-Dev@users.noreply.github.com> Date: Thu, 5 Sep 2024 17:57:05 -0400 Subject: [PATCH 07/19] Documentation --- scripts/check_codeblock_coverage.py | 93 +++++++++++++++++++++-------- 1 file changed, 68 insertions(+), 25 deletions(-) diff --git a/scripts/check_codeblock_coverage.py b/scripts/check_codeblock_coverage.py index 0c583d86c3..646f6a27b6 100644 --- a/scripts/check_codeblock_coverage.py +++ b/scripts/check_codeblock_coverage.py @@ -1,70 +1,108 @@ -import sys, os, re, argparse +import sys +import os +import re +import argparse from dataclasses import dataclass - @dataclass class CodeBlock: + """ + A class representing a code block in an .rst file. + + Attributes: + start (int): The starting line number of the code block. + file (str): The file path of the .rst file. + langs (list[str]): A list of languages found in the code block. + """ start: int file: str langs: list[str] +def get_all_rst_files(dir: str) -> list[str]: + """ + Recursively searches a directory for .rst files. + + Parameters: + dir (str): The directory path to search. -def get_all_rst_files(dir): + Returns: + list[str]: A list of file paths for .rst files. + """ files = [] for root, dirs, filenames in os.walk(dir): for filename in filenames: if filename.endswith(".rst"): files.append(os.path.join(root, filename)) - return files +def is_codeblock(line: str) -> bool: + """ + Checks if a line in an .rst file indicates the start of a code block. -def is_codeblock(line: str): + Parameters: + line (str): A line from the file. + + Returns: + bool: True if the line starts a code block, False otherwise. + """ return line.startswith(".. tab-set-code::") or line.startswith(".. tab-set::") +def get_blocks_from_rst_file(file: str) -> list[CodeBlock]: + """ + Extracts code blocks from a given .rst file. + + Parameters: + file (str): The path to the .rst file. -def get_blocks_from_rst_file(file: str): + Returns: + list[CodeBlock]: A list of CodeBlock instances representing the code blocks in the file. + """ blocks = [] - with (open(file, "r", encoding="utf8")) as f: + with open(file, "r", encoding="utf8") as f: block_start = None langs = [] for index, line in enumerate(f): if is_codeblock(line): if langs != []: blocks.append(CodeBlock(start=block_start, file=file, langs=langs)) - block_start = index + 1 langs = [] else: if line.startswith(" ") or line.startswith("\t"): - lang = re.search( - "(`{3}|:language: )(java|python|c\\+\\+)", line.lower() - ) + lang = re.search("(`{3}|:language: )(java|python|c\\+\\+)", line.lower()) if lang is not None: langs.append(lang.group(2)) return blocks +def generate_report(blocks: list[CodeBlock], langs: list[str], wordy: bool, output: str): + """ + Generates a report of code block coverage and writes it to the specified output. -def generate_report( - blocks: list[CodeBlock], langs: list[str], wordy: bool, output: str -): + Parameters: + blocks (list[CodeBlock]): A list of CodeBlock instances to analyze. + langs (list[str]): A list of languages to check for. + wordy (bool): Whether to include detailed missing code block information. + output (str): The path to the output file. + """ stream = sys.stdout if wordy: stream = open(output, "w") blocks_count = len(blocks) langs_coverage = {lang: 0 for lang in langs} + + # Calculate coverage for each language for block in blocks: for lang in langs: if lang in block.langs: langs_coverage[lang] += 1 + + # Print the coverage summary print(f"Total code blocks: {blocks_count}", file=stream) for lang, coverage in langs_coverage.items(): - print( - f"{lang} coverage: {coverage}/{blocks_count} ({coverage/blocks_count*100:.2f}%)", - file=stream, - ) + print(f"{lang} coverage: {coverage}/{blocks_count} ({coverage/blocks_count*100:.2f}%)", file=stream) + # If wordy flag is set, print detailed information about missing code blocks if wordy: print("\n\nMissing code blocks:", file=stream) for block in blocks: @@ -73,13 +111,16 @@ def generate_report( print(f"File: {block.file}, Line: {block.start}", file=stream) print(f"Missing languages: {missing_langs}", file=stream) - stream.close() - + # Close the output file if it was opened + if stream is not sys.stdout: + stream.close() def main(): - parser = argparse.ArgumentParser( - description="Check code block coverage in FRC docs" - ) + """ + The main entry point of the script. + """ + # Set up argument parsing + parser = argparse.ArgumentParser(description="Check code block coverage in FRC docs") parser.add_argument("--dir", type=str, help="Directory to search for rst files") parser.add_argument( "--wordy", @@ -99,9 +140,10 @@ def main(): help="Languages to check for", ) + # Parse the command line arguments args = parser.parse_args() - print(args.wordy) + # Get all .rst files from the specified directory files = get_all_rst_files(dir=args.dir) blocks = [] for file in files: @@ -110,10 +152,11 @@ def main(): continue else: blocks.extend(file_blocks) + + # Generate the report based on the collected code blocks generate_report( blocks=blocks, langs=args.langs, wordy=args.wordy, output=args.output ) - if __name__ == "__main__": main() From ac85b19e921330f13c976ee5cbce2b245ec00038 Mon Sep 17 00:00:00 2001 From: Falon <47285315+falOn-Dev@users.noreply.github.com> Date: Thu, 5 Sep 2024 18:01:03 -0400 Subject: [PATCH 08/19] Update CI.yml --- .github/workflows/CI.yml | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index b080592564..939dc7b182 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -186,3 +186,18 @@ jobs: - name: Format run: | black --check . + + check-codeblock-coverage: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: 3.9 + - name: Check Coverage + run: | + python scripts/check_codeblock_coverage.py --dir=source/docs/software --wordy --output=codeblock_coverage.txt + - uses: actions/upload-artifact@v4 + with: + name: codeblock-coverage + path: codeblock_coverage.txt \ No newline at end of file From 42af9cab6a738de0a830b5477d2e4cd6fa9fee5a Mon Sep 17 00:00:00 2001 From: Falon <47285315+falOn-Dev@users.noreply.github.com> Date: Thu, 5 Sep 2024 18:10:10 -0400 Subject: [PATCH 09/19] Black reformatting --- scripts/check_codeblock_coverage.py | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/scripts/check_codeblock_coverage.py b/scripts/check_codeblock_coverage.py index 646f6a27b6..9880330606 100644 --- a/scripts/check_codeblock_coverage.py +++ b/scripts/check_codeblock_coverage.py @@ -4,6 +4,7 @@ import argparse from dataclasses import dataclass + @dataclass class CodeBlock: """ @@ -14,10 +15,12 @@ class CodeBlock: file (str): The file path of the .rst file. langs (list[str]): A list of languages found in the code block. """ + start: int file: str langs: list[str] + def get_all_rst_files(dir: str) -> list[str]: """ Recursively searches a directory for .rst files. @@ -35,6 +38,7 @@ def get_all_rst_files(dir: str) -> list[str]: files.append(os.path.join(root, filename)) return files + def is_codeblock(line: str) -> bool: """ Checks if a line in an .rst file indicates the start of a code block. @@ -47,6 +51,7 @@ def is_codeblock(line: str) -> bool: """ return line.startswith(".. tab-set-code::") or line.startswith(".. tab-set::") + def get_blocks_from_rst_file(file: str) -> list[CodeBlock]: """ Extracts code blocks from a given .rst file. @@ -69,12 +74,17 @@ def get_blocks_from_rst_file(file: str) -> list[CodeBlock]: langs = [] else: if line.startswith(" ") or line.startswith("\t"): - lang = re.search("(`{3}|:language: )(java|python|c\\+\\+)", line.lower()) + lang = re.search( + "(`{3}|:language: )(java|python|c\\+\\+)", line.lower() + ) if lang is not None: langs.append(lang.group(2)) return blocks -def generate_report(blocks: list[CodeBlock], langs: list[str], wordy: bool, output: str): + +def generate_report( + blocks: list[CodeBlock], langs: list[str], wordy: bool, output: str +): """ Generates a report of code block coverage and writes it to the specified output. @@ -100,7 +110,10 @@ def generate_report(blocks: list[CodeBlock], langs: list[str], wordy: bool, outp # Print the coverage summary print(f"Total code blocks: {blocks_count}", file=stream) for lang, coverage in langs_coverage.items(): - print(f"{lang} coverage: {coverage}/{blocks_count} ({coverage/blocks_count*100:.2f}%)", file=stream) + print( + f"{lang} coverage: {coverage}/{blocks_count} ({coverage/blocks_count*100:.2f}%)", + file=stream, + ) # If wordy flag is set, print detailed information about missing code blocks if wordy: @@ -115,12 +128,15 @@ def generate_report(blocks: list[CodeBlock], langs: list[str], wordy: bool, outp if stream is not sys.stdout: stream.close() + def main(): """ The main entry point of the script. """ # Set up argument parsing - parser = argparse.ArgumentParser(description="Check code block coverage in FRC docs") + parser = argparse.ArgumentParser( + description="Check code block coverage in FRC docs" + ) parser.add_argument("--dir", type=str, help="Directory to search for rst files") parser.add_argument( "--wordy", @@ -152,11 +168,12 @@ def main(): continue else: blocks.extend(file_blocks) - + # Generate the report based on the collected code blocks generate_report( blocks=blocks, langs=args.langs, wordy=args.wordy, output=args.output ) + if __name__ == "__main__": main() From 60cd55f9fae5863eec272949d0b9af3bb2196959 Mon Sep 17 00:00:00 2001 From: Falon <47285315+falOn-Dev@users.noreply.github.com> Date: Sat, 7 Sep 2024 01:14:22 -0400 Subject: [PATCH 10/19] Update check_codeblock_coverage.py --- scripts/check_codeblock_coverage.py | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/scripts/check_codeblock_coverage.py b/scripts/check_codeblock_coverage.py index 9880330606..29c8626b1a 100644 --- a/scripts/check_codeblock_coverage.py +++ b/scripts/check_codeblock_coverage.py @@ -75,10 +75,14 @@ def get_blocks_from_rst_file(file: str) -> list[CodeBlock]: else: if line.startswith(" ") or line.startswith("\t"): lang = re.search( - "(`{3}|:language: )(java|python|c\\+\\+)", line.lower() + "(`{3}|:language: )(java|python|c\\+\\+|kotlin)", line.lower() ) if lang is not None: langs.append(lang.group(2)) + + if langs != []: + blocks.append(CodeBlock(start=block_start, file=file, langs=langs)) + return blocks @@ -176,4 +180,4 @@ def main(): if __name__ == "__main__": - main() + main() \ No newline at end of file From 8102ad35ab111bdde8d85c75162a5872aa6c3cd1 Mon Sep 17 00:00:00 2001 From: Falon <47285315+falOn-Dev@users.noreply.github.com> Date: Sat, 7 Sep 2024 01:33:52 -0400 Subject: [PATCH 11/19] No more CI codeblock coverage --- .github/workflows/CI.yml | 17 +---------------- 1 file changed, 1 insertion(+), 16 deletions(-) diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index 939dc7b182..b09c76c44f 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -185,19 +185,4 @@ jobs: pip install -r source/requirements.txt - name: Format run: | - black --check . - - check-codeblock-coverage: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - uses: actions/setup-python@v5 - with: - python-version: 3.9 - - name: Check Coverage - run: | - python scripts/check_codeblock_coverage.py --dir=source/docs/software --wordy --output=codeblock_coverage.txt - - uses: actions/upload-artifact@v4 - with: - name: codeblock-coverage - path: codeblock_coverage.txt \ No newline at end of file + black --check . \ No newline at end of file From 4ee14bdfd1cd5f2c0140376eb1231e73c55d1d0e Mon Sep 17 00:00:00 2001 From: Falon <47285315+falOn-Dev@users.noreply.github.com> Date: Sat, 7 Sep 2024 01:34:07 -0400 Subject: [PATCH 12/19] dynamically create the regex --- scripts/check_codeblock_coverage.py | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/scripts/check_codeblock_coverage.py b/scripts/check_codeblock_coverage.py index 29c8626b1a..6ba317353f 100644 --- a/scripts/check_codeblock_coverage.py +++ b/scripts/check_codeblock_coverage.py @@ -51,8 +51,19 @@ def is_codeblock(line: str) -> bool: """ return line.startswith(".. tab-set-code::") or line.startswith(".. tab-set::") +def generate_language_regex(langs: list[str]) -> str: + """ + Generates a regex pattern to match the specified languages. + + Parameters: + langs (list[str]): A list of languages to match. + + Returns: + str: A regex pattern to match the specified languages. + """ + return f"(`{{3}}|:language: )({'|'.join(langs)})".replace("+", r"\+") -def get_blocks_from_rst_file(file: str) -> list[CodeBlock]: +def get_blocks_from_rst_file(file: str, langs: list[str]) -> list[CodeBlock]: """ Extracts code blocks from a given .rst file. @@ -63,6 +74,7 @@ def get_blocks_from_rst_file(file: str) -> list[CodeBlock]: list[CodeBlock]: A list of CodeBlock instances representing the code blocks in the file. """ blocks = [] + lang_regex = generate_language_regex(langs) with open(file, "r", encoding="utf8") as f: block_start = None langs = [] @@ -75,7 +87,7 @@ def get_blocks_from_rst_file(file: str) -> list[CodeBlock]: else: if line.startswith(" ") or line.startswith("\t"): lang = re.search( - "(`{3}|:language: )(java|python|c\\+\\+|kotlin)", line.lower() + lang_regex, line.lower() ) if lang is not None: langs.append(lang.group(2)) @@ -156,18 +168,21 @@ def main(): parser.add_argument( "--langs", nargs="+", - default=["java", "python", "c++"], + default=['java', 'python', 'c++'], help="Languages to check for", ) + # Parse the command line arguments args = parser.parse_args() + print(generate_language_regex(args.langs)) + # Get all .rst files from the specified directory files = get_all_rst_files(dir=args.dir) blocks = [] for file in files: - file_blocks = get_blocks_from_rst_file(file) + file_blocks = get_blocks_from_rst_file(file, args.langs) if len(file_blocks) == 0: continue else: From e31c46eb337eb7d6c18f16c69b7077545ad8ca38 Mon Sep 17 00:00:00 2001 From: Falon <47285315+falOn-Dev@users.noreply.github.com> Date: Sat, 7 Sep 2024 01:35:50 -0400 Subject: [PATCH 13/19] Change "wordy" to "verbose" --- scripts/check_codeblock_coverage.py | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/scripts/check_codeblock_coverage.py b/scripts/check_codeblock_coverage.py index 6ba317353f..912bf5b18f 100644 --- a/scripts/check_codeblock_coverage.py +++ b/scripts/check_codeblock_coverage.py @@ -99,7 +99,7 @@ def get_blocks_from_rst_file(file: str, langs: list[str]) -> list[CodeBlock]: def generate_report( - blocks: list[CodeBlock], langs: list[str], wordy: bool, output: str + blocks: list[CodeBlock], langs: list[str], verbose: bool, output: str ): """ Generates a report of code block coverage and writes it to the specified output. @@ -107,11 +107,11 @@ def generate_report( Parameters: blocks (list[CodeBlock]): A list of CodeBlock instances to analyze. langs (list[str]): A list of languages to check for. - wordy (bool): Whether to include detailed missing code block information. + verbose (bool): Whether to include detailed missing code block information. output (str): The path to the output file. """ stream = sys.stdout - if wordy: + if verbose: stream = open(output, "w") blocks_count = len(blocks) @@ -131,8 +131,8 @@ def generate_report( file=stream, ) - # If wordy flag is set, print detailed information about missing code blocks - if wordy: + # If verbose flag is set, print detailed information about missing code blocks + if verbose: print("\n\nMissing code blocks:", file=stream) for block in blocks: missing_langs = [lang for lang in langs if lang not in block.langs] @@ -155,7 +155,7 @@ def main(): ) parser.add_argument("--dir", type=str, help="Directory to search for rst files") parser.add_argument( - "--wordy", + "--verbose", action="store_true", help="Outputs which code blocks are missing languages", ) @@ -190,7 +190,7 @@ def main(): # Generate the report based on the collected code blocks generate_report( - blocks=blocks, langs=args.langs, wordy=args.wordy, output=args.output + blocks=blocks, langs=args.langs, verbose=args.verbose, output=args.output ) From bd3b68a068b6ff2949ba2af17229e74d490842c1 Mon Sep 17 00:00:00 2001 From: Falon <47285315+falOn-Dev@users.noreply.github.com> Date: Sat, 7 Sep 2024 01:36:01 -0400 Subject: [PATCH 14/19] Left in debug statement on accident --- scripts/check_codeblock_coverage.py | 2 - .../contributing/frc-docs/translations.rd | 47 +++ source/docs/contributing/wpilib/index.rd | 39 +++ .../control-system-hardware.rd | 329 ++++++++++++++++++ .../control-system-software.rd | 160 +++++++++ .../hardware-basics/can-wiring-basics.rd | 24 ++ source/docs/hardware/hardware-basics/index.rd | 14 + .../preemptive-troubleshooting.rd | 161 +++++++++ .../hardware/hardware-basics/robot-battery.rd | 200 +++++++++++ .../hardware-basics/status-lights-ref.rd | 0 10 files changed, 974 insertions(+), 2 deletions(-) create mode 100644 source/docs/contributing/frc-docs/translations.rd create mode 100644 source/docs/contributing/wpilib/index.rd create mode 100644 source/docs/controls-overviews/control-system-hardware.rd create mode 100644 source/docs/controls-overviews/control-system-software.rd create mode 100644 source/docs/hardware/hardware-basics/can-wiring-basics.rd create mode 100644 source/docs/hardware/hardware-basics/index.rd create mode 100644 source/docs/hardware/hardware-basics/preemptive-troubleshooting.rd create mode 100644 source/docs/hardware/hardware-basics/robot-battery.rd create mode 100644 source/docs/hardware/hardware-basics/status-lights-ref.rd diff --git a/scripts/check_codeblock_coverage.py b/scripts/check_codeblock_coverage.py index 912bf5b18f..efbda8b12b 100644 --- a/scripts/check_codeblock_coverage.py +++ b/scripts/check_codeblock_coverage.py @@ -176,8 +176,6 @@ def main(): # Parse the command line arguments args = parser.parse_args() - print(generate_language_regex(args.langs)) - # Get all .rst files from the specified directory files = get_all_rst_files(dir=args.dir) blocks = [] diff --git a/source/docs/contributing/frc-docs/translations.rd b/source/docs/contributing/frc-docs/translations.rd new file mode 100644 index 0000000000..bd1ec93e74 --- /dev/null +++ b/source/docs/contributing/frc-docs/translations.rd @@ -0,0 +1,47 @@ +Translations +============ + +frc-docs supports translations using the web-based `Transifex `__ utility. frc-docs has been translated into Spanish - Mexico (es_MX), French - Canada (fr_CA) and Turkish - Turkey (tr_TR). Chinese - China (zh_CN), Hebrew - Israel (he_IL), and Portuguese - Brazil (pt_BR) have translations in progress. Translators that are fluent in *both* English and one of the specified languages would be greatly appreciated to contribute to the translations. Even once a translation is complete, it needs to be updated to keep up with changes in frc-docs. + +Workflow +-------- + +Here are some steps to follow for translating frc-docs. + +1. Sign up for `Transifex `__ and ask to join the `frc-docs project `__, and request access to the language you'd like to contribute to. +2. Join GitHub `discussions `__! This is a direct means of communication with the WPILib team. You can use this to ask us questions in a fast and streamlined fashion. +3. You may be contacted and asked questions involving contributing languages before being granted access to the frc-docs translation project. +4. Translate your language! + +Links +----- + +Links must be preserved in their original syntax. To translate a link, you can replace the TRANSLATE ME text (this will be replaced with the English title) with the appropriate translation. + +An example of the original text may be + +.. code-block:: text + + For complete wiring instructions/diagrams, please see the :doc:`Wiring the FRC Control System Document `. + +where the ``Wiring the FRC Control System Document`` then gets translated. + +.. code-block:: text + + For complete wiring instructions/diagrams, please see the :doc:`TRANSLATED TEXT `. + +Another example is below + +.. code-block:: text + + For complete wiring instructions/diagrams, please see the :ref:`TRANSLATED TEXT ` + +Publishing Translations +----------------------- + +Translations are pulled from Transifex and published automatically each day. + +Accuracy +-------- + +Translations should be accurate to the original text. If improvements to the English text can be made, open a PR or issue on the `frc-docs `__ repository. These can then get translated on merge. diff --git a/source/docs/contributing/wpilib/index.rd b/source/docs/contributing/wpilib/index.rd new file mode 100644 index 0000000000..e12cdc7621 --- /dev/null +++ b/source/docs/contributing/wpilib/index.rd @@ -0,0 +1,39 @@ +.. include:: + +Developing with allwpilib +========================= + +.. important:: This document contains information for developers *of* WPILib. This is not for programming FRC\ |reg| robots. + +This is a list of links to the various documentation for the `allwpilib `__ repository. + +Quick Start +----------- + +Below is a list of instructions that guide you through cloning, building, publishing and using local allwpilib binaries in a robot project. This quick start is not intended as a replacement for the information that is further listed in this document. + +* Clone the repository with ``git clone https://github.com/wpilibsuite/allwpilib.git`` +* Build the repository with ``./gradlew build`` or ``./gradlew build --build-cache`` if you have an internet connection +* Publish the artifacts locally by running ``./gradlew publish`` +* `Update your robot project's `__ ``build.gradle`` `to use the artifacts `__ + +Core Repository +--------------- +.. toctree:: + :maxdepth: 1 + + Overview + Styleguide & wpiformat + Building with CMake + Using Development Builds + Maven Artifacts + Contributor Guidelines + +NetworkTables +------------- + +.. toctree:: + :maxdepth: 1 + + NetworkTables 4 Protocol Spec + NetworkTables 3 Protocol Spec diff --git a/source/docs/controls-overviews/control-system-hardware.rd b/source/docs/controls-overviews/control-system-hardware.rd new file mode 100644 index 0000000000..cacc1d3905 --- /dev/null +++ b/source/docs/controls-overviews/control-system-hardware.rd @@ -0,0 +1,329 @@ +.. include:: + +Hardware Component Overview +=========================== + +The goal of this document is to provide a brief overview of the hardware components that make up the FRC\ |reg| Control System. Each component will contain a brief description of the component function and a link to more documentation. + +.. note:: For wiring instructions/diagrams, please see the :doc:`Wiring the FRC Control System ` document. + +Overview of Control System +-------------------------- + +.. tab-set:: + .. tab-item:: REV + :sync: rev + + .. figure:: images/frc-control-system-layout-rev.svg + :alt: Layout of all popular components of the control system including REV Control System Components + :width: 500 + + Diagram courtesy of FRC\ |reg| Team 3161 and Stefen Acepcion. + + .. tab-item:: CTRE + :sync: ctre + + .. figure:: images/frc-control-system-layout.svg + :alt: Layout of all of the core components of the control system and how they are connected. + :width: 500 + + Diagram courtesy of FRC\ |reg| Team 3161 and Stefen Acepcion. + +NI roboRIO +---------- + +.. image:: images/control-system-hardware/roborio.png + :alt: NI roboRIO + :width: 500 + +The :ref:`NI-roboRIO ` is the main robot controller used for FRC. The roboRIO serves as the "brain" for the robot running team-generated code that commands all of the other hardware. + +CTRE Power Distribution Panel +----------------------------- + +.. image:: images/control-system-hardware/power-distribution-panel.png + :alt: CTRE Power Distribution Panel + :width: 500 + +The :ref:`CTRE Power Distribution Panel ` (PDP) is designed to distribute power from a 12VDC battery to various robot components through auto-resetting circuit breakers and a small number of special function fused connections. The PDP provides 8 output pairs rated for 40A continuous current and 8 pairs rated for 30A continuous current. The PDP provides dedicated 12V connectors for the roboRIO, as well as connectors for the Voltage Regulator Module and Pneumatics Control Module. It also includes a CAN interface for logging current, temperature, and battery voltage. For more detailed information, see the `PDP User Manual `__. + +REV Power Distribution Hub +-------------------------- + +.. image:: images/control-system-hardware/power-distribution-hub.png + :alt: REV Power Distribution Hub + :width: 500 + +The `REV Power Distribution Hub `__ (PDH) is designed to distribute power from a 12VDC battery to various robot components. The PDH features 20 high-current (40A max) channels, 3 low-current (15A max), and 1 switchable low-current channel. The Power Distribution Hub features toolless latching WAGO terminals, an LED voltage display, and the ability to connect over CAN or USB-C to the REV Hardware Client for real-time telemetry. + +CTRE Voltage Regulator Module +----------------------------- + +.. image:: images/control-system-hardware/voltage-regulator-module.png + :alt: CTRE Voltage Regulator Module + :width: 500 + +The CTRE Voltage Regulator Module (VRM) is an independent module that is powered by 12 volts. The device is wired to a dedicated connector on the PDP. The module has multiple regulated 12V and 5V outputs. The purpose of the VRM is to provide regulated power for the robot radio, custom circuits, and IP vision cameras. For more information, see the `VRM User Manual `__. + +REV Radio Power Module +---------------------- + +.. image:: images/control-system-hardware/radio-power-module.png + :alt: REV Radio Power Module + :width: 500 + +The `REV Radio Power Module `__ is designed to keep one of the most critical system components, the OpenMesh WiFi radio, powered in the toughest moments of the competition. The Radio Power Module eliminates the need for powering the radio through a traditional barrel power jack. Utilizing 18V Passive POE with two socketed RJ45 connectors, the Radio Power Module passes signal between the radio and roboRIO while providing power directly to the radio. After connecting the radio and roboRIO, easily add power to the Radio Power Module by wiring it to the low-current channels on the Power Distribution Hub utilizing the color coded push button WAGO terminals. + +OpenMesh OM5P-AN or OM5P-AC Radio +--------------------------------- + +.. image:: images/control-system-hardware/openmesh-radio.png + :alt: OpenMesh OM5P-AN or OM5P-AC Radio + :width: 500 + +Either the OpenMesh OM5P-AN or `OpenMesh OM5P-AC `__ wireless radio is used as the robot radio to provide wireless communication functionality to the robot. The device can be configured as an Access Point for direct connection of a laptop for use at home. It can also be configured as a bridge for use on the field. The robot radio should be powered by one of the 12V/2A outputs on the VRM and connected to the roboRIO controller over Ethernet. For more information, see :ref:`Programming your Radio `. + +The OM5P-AN `is no longer available for purchase `__. The OM5P-AC is slightly heavier, has more cooling grates, and has a rough surface texture compared to the OM5P-AN. + +120A Circuit Breaker +-------------------- + +.. image:: images/control-system-hardware/circuit-breaker.png + :alt: 120A Circuit Breaker + :width: 500 + +The 120A Main Circuit Breaker serves two roles on the robot: the main robot power switch and a protection device for downstream robot wiring and components. The 120A circuit breaker is wired to the positive terminals of the robot battery and Power Distribution boards. For more information, please see the `Cooper Bussmann 18X Series Datasheet (PN: 185120F) `__ + +Snap Action Circuit Breakers +---------------------------- + +.. image:: images/control-system-hardware/snap-action-circuit-breaker.png + :alt: Snap Action Circuit Breakers to be inserted in the PDP. + :width: 500 + +The Snap Action circuit breakers, `MX5 series `__ and `VB3 Series `__, are used with the Power Distribution Panel to limit current to branch circuits. The ratings on these circuit breakers are for continuous current, temporary peak values can be considerably higher. + +Robot Battery +------------- + +.. image:: images/control-system-hardware/robot-battery.png + :alt: Robot Battery + :width: 500 + +The power supply for an FRC robot is a single 12V 18Ah Sealed Lead Acid (SLA) battery, capable of meeting the high current demands of an FRC robot. For more information, see the :ref:`Robot Battery page. ` + +.. note:: Multiple battery part numbers may be legal, consult the `FRC Manual `__ for a complete list. + +Robot Signal Light +------------------ + +.. tab-set:: + + .. tab-item:: Allen-Bradley + + .. figure:: images/control-system-hardware/rsl-allenbradley.jpg + :alt: Orange Robot Signal Light (Allen-Bradley) + :width: 500 + + Allen-Bradley 855PB-B12ME522 + + .. tab-item:: AndyMark + + .. figure:: images/control-system-hardware/rsl-andymark.png + :alt: Orange Robot Signal Light (AndyMark) + :width: 500 + + AndyMark am-3583 + +The Robot Signal Light (RSL) is required to be either Allen-Bradley 855PB-B12ME522 or AndyMark am-3583. It is directly controlled by the roboRIO and will flash when enabled and stay solid while disabled. + +CTRE Pneumatics Control Module +------------------------------ + +.. image:: images/control-system-hardware/pneumatics-control-module.png + :alt: CTRE Pneumatics Control Module + :width: 500 + +The :ref:`CTRE Pneumatics Control Module ` (PCM) contains all of the inputs and outputs required to operate 12V or 24V pneumatic solenoids and the on board compressor. The PCM contains an input for the pressure sensor and will control the compressor automatically when the robot is enabled and a solenoid has been created in the code. For more information see the `PCM User Manual `__. + +REV Pneumatic Hub +----------------- + +.. image:: images/control-system-hardware/pneumatic-hub.png + :alt: REV Pneumatic Hub + :width: 500 + +The `REV Pneumatic Hub `__ is a standalone module that is capable of switching both 12V and 24V pneumatic solenoid valves. The Pneumatic Hub features 16 solenoid channels which allow for up to 16 single-acting solenoids, 8 double-acting solenoids, or a combination of the two types. The user selectable output voltage is fully regulated, allowing even 12V solenoids to stay active when the robot battery drops as low as 4.75V. + +Digital and analog pressure sensor ports are built into the device, increasing the flexibility and feedback functionality of the pneumatic system. The USB-C connection on the Hub works with the REV Hardware Client, allowing users to test pneumatic systems without a need for an additional robot controller. + +Motor Controllers +----------------- + +There are a variety of different :ref:`motor controllers ` which work with the FRC Control System and are approved for use. These devices are used to provide variable voltage control of the brushed and brushless DC motors used in FRC. They are listed here in order of `usage `__. + +.. note:: 3rd Party CAN control is not supported from WPILib. See this section on :ref:`docs/software/can-devices/third-party-devices:Third-Party CAN Devices` for more information. + +Talon SRX +^^^^^^^^^ + +.. image:: images/control-system-hardware/talonsrx-motor-controller.png + :alt: Talon SRX + :width: 500 + +The `Talon SRX Motor Controller `__ is a "smart motor controller" from Cross The Road Electronics/VEX Robotics. The Talon SRX can be controlled over the CAN bus or :term:`PWM` interface. When using the CAN bus control, this device can take inputs from limit switches and potentiometers, encoders, or similar sensors in order to perform advanced control. For more information see the `Talon SRX User's Guide `__. + +Victor SPX +^^^^^^^^^^ + +.. image:: images/control-system-hardware/victor-spx-motor-controller.png + :alt: Victor SPX + :width: 500 + +The `Victor SPX Motor Controller `__ is a CAN or PWM controlled motor controller from Cross The Road Electronics/VEX Robotics. The device is connectorized to allow easy connection to the roboRIO PWM connectors or a CAN bus. The case is sealed to prevent debris from entering the controller. For more information, see the `Victor SPX User Guide `__. + +SPARK MAX Motor Controller +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. image:: images/control-system-hardware/spark-max-motor-controller.png + :alt: SPARK MAX Motor Controller + :width: 400 + +The `SPARK MAX Motor Controller `__ is an advanced brushed and brushless DC motor controller from REV Robotics. When using CAN bus or USB control, the SPARK MAX uses input from limit switches, encoders, and other sensors, including the integrated encoder of the REV NEO Brushless Motor, to perform advanced control modes. The SPARK MAX can be controlled over PWM, CAN or USB (for configuration/testing only). For more information, see the `SPARK MAX User's Manual `__. + +TalonFX Motor Controller +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. image:: images/control-system-hardware/talonfx.png + :alt: TalonFX Motor Controller + :width: 500 + +The `TalonFX Motor Controller `__ is integrated into the Falcon 500 brushless motor. It features an integrated encoder and all of the smart features of the Talon SRX and more! For more information see the `Falcon 500 User Guide `__. + +SPARK Motor Controller +^^^^^^^^^^^^^^^^^^^^^^ + +.. image:: images/control-system-hardware/spark-motor-controller.png + :alt: SPARK Motor Controller + :width: 400 + +.. warning:: While this motor controller is still legal for FRC use, the manufacturer has discontinued this product. + +The `SPARK Motor Controller `__ from REV Robotics is an inexpensive brushed DC motor controller. The SPARK is controlled using the PWM interface. Limit switches may be wired directly to the SPARK to limit motor travel in one or both directions. + +Victor SP +^^^^^^^^^ + +.. image:: images/control-system-hardware/victor-sp-motor-controller.png + :alt: Victor SP + :width: 500 + +.. warning:: While this motor controller is still legal for FRC use, the manufacturer has discontinued this product. + +The `Victor SP Motor Controller `__ is a PWM motor controller from Cross The Road Electronics/VEX Robotics. The Victor SP has an electrically isolated metal housing for heat dissipation, making the use of the fan optional. The case is sealed to prevent debris from entering the controller. The controller is approximately half the size of previous models. + +Talon Motor Controller +^^^^^^^^^^^^^^^^^^^^^^ + +.. image:: images/control-system-hardware/talon-motor-controller.png + :alt: Talon Motor Controller + +.. warning:: While this motor controller is still legal for FRC use, the manufacturer has discontinued this product. + +The `Talon Motor Controller `__ from Cross the Road Electronics is a PWM controlled brushed DC motor controller with passive cooling. + +Victor 888 Motor Controller / Victor 884 Motor Controller +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. image:: images/control-system-hardware/victor-888-motor-controller.png + :alt: Victor 888 Motor Controller + :width: 400 + +.. warning:: While this motor controller is still legal for FRC use, the manufacturer has discontinued this product. + +The `Victor 884 `__ and `Victor 888 `__ motor controllers from VEX Robotics are variable speed PWM motor controllers for use in FRC. The Victor 888 replaces the Victor 884, which is also usable in FRC. + +Jaguar Motor Controller +^^^^^^^^^^^^^^^^^^^^^^^ + +.. image:: images/control-system-hardware/jaguar-motor-controller.png + :alt: Jaguar Motor Controller + :width: 500 + +.. warning:: While this motor controller is still legal for FRC use, the manufacturer has discontinued this product. + +The `Jaguar Motor Controller `__ from VEX Robotics (formerly made by Luminary Micro and Texas Instruments) is a variable speed motor controller for use in FRC. For FRC, the Jaguar may only be controlled using the PWM interface. + +DMC-60 and DMC-60C Motor Controller +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. image:: images/control-system-hardware/dmc-60c-motor-controller.png + :alt: DMC-60C Motor Controller + :width: 500 + +.. warning:: While this motor controller is still legal for FRC use, the manufacturer has discontinued this product. + +The DMC-60 is a PWM motor controller from Digilent. The DMC-60 features integrated thermal sensing and protection including current-foldback to prevent overheating and damage, and four multi-color LEDs to indicate speed, direction, and status for easier debugging. For more information, see the `DMC-60 reference manual `__ + +The DMC-60C adds CAN smart controller capabilities to the DMC-60 controller. Due to the manufacturer discontinuing this product, the DMC-60C is only usable with PWM. For more information see the `DMC-60C Product Page `__ + +Venom Motor Controller +^^^^^^^^^^^^^^^^^^^^^^ + +.. image:: images/control-system-hardware/venom.jpg + :alt: Venom Motor Controller + :width: 500 + +The `Venom Motor Controller `__ from Playing With Fusion is integrated into a motor based on the original :term:`CIM`. Speed, current, temperature, and position are all measured onboard, enabling advanced control modes without complicated sensing and wiring schemes. + +Nidec Dynamo BLDC Motor with Controller +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. image:: images/control-system-hardware/nidec-dynamo.jpg + :alt: Nidec Dynamo BLDC Motor with Controller + :width: 500 + +The `Nidec Dynamo BLDC Motor with Controller `__ is the first brushless motor and controller legal in FRC. This motor's controller is integrated into the back of the motor. The `motor data sheet `__ provides more device specifics. + +SD540B and SD540C Motor Controllers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. image:: images/control-system-hardware/sd540b-pwm.png + :alt: SD540B Motor Controller + :width: 500 + +The SD540B and SD540C Motor Controllers from Mindsensors are controlled using PWM. CAN control is no longer available for the SD540C due to lack of manufacturer support. Limit switches may be wired directly to the SD540 to limit motor travel in one or both directions. For more information see the `Mindsensors FRC page `__ + +Spike H-Bridge Relay +-------------------- + +.. image:: images/control-system-hardware/spike-relay.png + :alt: Spike H-Bridge Relay + :width: 300 + +.. warning:: While this relay is still legal for FRC use, the manufacturer has discontinued this product. + +The Spike H-Bridge Relay from VEX Robotics is a device used for controlling power to motors or other custom robot electronics. When connected to a motor, the Spike provides On/Off control in both the forward and reverse directions. The Spike outputs are independently controlled so it can also be used to provide power to up to 2 custom electronic circuits. The Spike H-Bridge Relay should be connected to a relay output of the roboRIO and powered from the Power Distribution Panel. For more information, see the `Spike User’s Guide `__. + +Servo Power Module +------------------ + +.. image:: images/control-system-hardware/servo-power-module.png + :alt: Servo Power Module + :width: 300 + +The Servo Power Module from Rev Robotics is capable of expanding the power available to servos beyond what the roboRIO integrated power supply is capable of. The Servo Power Module provides up to 90W of 6V power across 6 channels. All control signals are passed through directly from the roboRIO. For more information, see the `Servo Power Module webpage `__. + +Microsoft Lifecam HD3000 +------------------------ + +.. image:: images/control-system-hardware/microsoft-lifecam.png + :alt: Microsoft Lifecam HD3000 + :width: 300 + +The Microsoft Lifecam HD3000 is a USB webcam that can be plugged directly into the roboRIO. The camera is capable of capturing up to 1280x720 video at 30 FPS. For more information about the camera, see the `Microsoft product page `__. For more information about using the camera with the roboRIO, see the :ref:`Vision Processing ` section of this documentation. + +Image Credits +------------- + +Image of roboRIO courtesy of National Instruments. Image of DMC-60 courtesy of Digilent. Image of SD540 courtesy of Mindsensors. Images of Jaguar Motor Controller, Talon SRX, Talon FX, Victor 888, Victor SP, Victor SPX, and Spike H-Bridge Relay courtesy of VEX Robotics, Inc. Image of SPARK MAX, Power Distribution Hub, Radio Power Module, and Pneumatic Hub courtesy of REV Robotics. Lifecam, PDP, PCM, SPARK, and VRM photos courtesy of *FIRST*\ |reg|. All other photos courtesy of AndyMark Inc. diff --git a/source/docs/controls-overviews/control-system-software.rd b/source/docs/controls-overviews/control-system-software.rd new file mode 100644 index 0000000000..453c4c4d33 --- /dev/null +++ b/source/docs/controls-overviews/control-system-software.rd @@ -0,0 +1,160 @@ +.. include:: + +Software Component Overview +=========================== + +The FRC\ |reg| software consists of a wide variety of mandatory and optional components. These elements are designed to assist you in the design, development, and debugging of your robot code as well as assist with control robot operation and to provide feedback when troubleshooting. For each software component this document will provide a brief overview of its purpose, a link to the package download, if appropriate, and a link to further documentation where available. + +Operating System Compatibility +------------------------------ + +The primary supported OS for FRC components is Windows. All required FRC software components have been tested on Windows 10 & 11. + +Many of the tools for C++/Java/Python programming are also supported and tested on macOS and Linux. Teams programming in C++/Java/Python should be able to develop using these systems, using a Windows system for the Windows-only operations such as the Driver Station, Radio Configuration Utility, and roboRIO Imaging Tool. + +LabVIEW FRC (Windows Only) +-------------------------- + +.. image:: /docs/zero-to-robot/step-4/images/creating-test-program-labview/creating-a-project.png + :alt: LabVIEW FRC Getting Started screen. + +LabVIEW FRC, based on a recent version of LabVIEW Professional, is one of the three officially supported languages for programming an FRC robot. LabVIEW is a graphical, dataflow-driven language. LabVIEW programs consist of a collection of icons, called VIs, wired together with wires which pass data between the VIs. The LabVIEW FRC installer is distributed on a DVD found in the Kickoff Kit of Parts and is also available for download. A guide to getting started with the LabVIEW FRC software, including installation instructions can be found :ref:`here `. + +Visual Studio Code +------------------ + +.. image:: images/control-system-software/visual-studio-code.png + :alt: Welcome screen of Visual Studio Code. + +Visual Studio Code is the supported development environment for C++, Java. A guide to getting started with Java and C++ for FRC, including the installation and configuration of Visual Studio Code can be found :ref:`here `. + +FRC Driver Station Powered by NI LabVIEW (Windows Only) +------------------------------------------------------- + +.. image:: images/control-system-software/frc-driver-station.png + :alt: Driver Station on the first tab with the robot disabled and disconnected. + +This is the only software allowed to be used for the purpose of controlling the state of the robot during competition. This software sends data to your robot from a variety of input devices. It also contains a number of tools used to help troubleshoot robot issues. More information about the FRC Driver Station Powered by NI LabVIEW can be found :ref:`here `. + +Dashboard Options +----------------- + +LabVIEW Dashboard (Windows Only) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. image:: images/control-system-software/frc-labview-dashboard.png + :alt: The default LabVIEW Dashboard on the Drive tab. + +The LabVIEW Dashboard is automatically launched by the FRC Driver Station by default. The purpose of the Dashboard is to provide feedback about the operation of the robot using tabbed display with a variety of built in features. More information about the FRC Default Dashboard software can be found :ref:`here `. + +SmartDashboard +^^^^^^^^^^^^^^ + +.. image:: images/control-system-software/smartdashboard.png + :alt: SmartDashboard with 3 widgets added. + +SmartDashboard allows you to view your robot data by automatically creating customizable indicators specifically for each piece of data sent from your robot. Additional documentation on SmartDashboard can be found :ref:`here `. + +Shuffleboard +^^^^^^^^^^^^ + +.. image:: images/control-system-software/shuffleboard.png + :alt: Shuffleboard with 3 widgets from their NetworkTables entries added. + +Shuffleboard has the same features as SmartDashboard. It also improves on the setup and visualization of your data with new features and a modern design at the cost of being less resource efficient. Additional documentation on Shuffleboard can be found :ref:`here `. + +Glass +^^^^^ + +.. image:: images/control-system-software/glass.png + :alt: Glass connected and showing NetworkTables, a Field2D window, and a plot of a couple signals. + +:ref:`Glass ` is a Dashboard focused on being a programmer's tool for debugging. The primary advantages are the field view, pose visualization and advanced signal plotting tools. + +LiveWindow +---------- + +.. image:: images/control-system-software/livewindow-smartdashboard.png + :alt: LiveWindow showing two different subsystems. + +LiveWindow is a feature of SmartDashboard and Shuffleboard, designed for use with the Test Mode of the Driver Station. LiveWindow allows the user to see feedback from sensors on the robot and control actuators independent of the written user code. More information about LiveWindow can be found :ref:`here `. + +FRC roboRIO Imaging Tool (Windows Only) +--------------------------------------- + +.. image:: /docs/zero-to-robot/step-3/images/imaging-your-roborio/roborio-imaging-tool.png + :alt: roboRIO Imaging Tool after it has found a connected roboRIO. + +This tool is used to format and setup a roboRIO for use in FRC. Installation instructions can be found :ref:`here `. Additional instructions on imaging your roboRIO using this tool can be found :doc:`here `. + +FRC Radio Configuration Utility (Windows Only) +---------------------------------------------- + +.. image:: images/control-system-software/frc-radio-configuration-utility.png + :alt: Initial screen of the FRC Radio Configuration Utility. + +The FRC Radio Configuration Utility is a tool used to configure the standard radio for practice use at home. This tool sets the appropriate network settings to mimic the experience of the FRC playing field. The FRC Radio Configuration Utility is installed by a standalone installer that can be found :ref:`here `. + +FRC Driver Station Log Viewer (Windows Only) +-------------------------------------------- + +.. image:: images/control-system-software/frc-log-viewer.png + :alt: Driver Station Log Viewer showing a logged practice session. + +The FRC Driver Station Log Viewer is used to view logs created by the FRC Driver Station. These logs contain a variety of information important for understanding what happened during a practice session or FRC match. More information about the FRC Driver Station Log Viewer and understanding the logs can be found :ref:`here ` + +RobotBuilder +------------ + +.. image:: images/control-system-software/robot-builder.png + :alt: RobotBuilder building a robot with two subsystems. + +RobotBuilder is a tool designed to aid in setup and structuring of a Command Based robot project for C++ or Java (Python not currently supported). RobotBuilder allows you to enter in the various components of your robot subsystems and operator interface and define what your commands are in a graphical tree structure. RobotBuilder will then generate structural template code to get you started. More information about RobotBuilder can be found :ref:`here `. More information about the Command Based programming architecture can be found :ref:`here `. + +Robot Simulation +---------------- + +.. image:: images/control-system-software/sim-gui.png + :alt: The Simulation GUI similar to Glass but also has Joysticks and control over the robot state and a few other features. + +Robot Simulation offers a way for Java, C++, and Python teams to verify their actual robot code is working in a simulated environment. This simulation can be launched directly from VS Code and includes a 2D field that users can visualize their robot's movement on. For more information see the :ref:`Robot Simulation section `. + +FRC LabVIEW Robot Simulator (Windows Only) +------------------------------------------ + +.. image:: images/control-system-software/robot-simulator.png + :alt: FRC LabVIEW Robot Simulator + +The FRC Robot Simulator is a component of the LabVIEW programming environment that allows you to operate a predefined robot in a simulated environment to test code and/or Driver Station functions. Information on using the FRC Robot Simulator can be found `here `__ or by opening the Robot Simulation Readme.html file in the LabVIEW Project Explorer. + +PathWeaver +---------- + +.. image:: images/control-system-software/pathweaver.png + :alt: PathWeaver UI with a project for FRC Deep Space plotting a trajectory to the back of the rocket. + +PathWeaver allows teams to quickly generate and configure paths for advanced autonomous routines. These paths have smooth curves allowing the team to quickly navigate their robot between points on the field. For more information see the :ref:`PathWeaver section `. + +System Identification +--------------------- + +.. image:: images/control-system-software/sysid.png + :alt: SysId UI showing diagnostics and analysis for a flywheel. + +This tool helps teams automatically calculate constants that can be used to describe the physical properties of your robot for use in features like robot simulation, trajectory following, and PID control. For more information see the :ref:`System Identification section `. + +OutlineViewer +------------- + +.. image:: images/control-system-software/outline-viewer.png + :alt: OutlineViewer with the preferences dialog box. + +OutlineViewer is a utility used to view, modify and add to all of the contents of the NetworkTables for debugging purposes. LabVIEW teams can use the Variables tab of the LabVIEW Dashboard to accomplish this functionality. For more information see the :ref:`Outline Viewer section `. + +roboRIO Team Number Setter +-------------------------- + +.. image:: /docs/software/wpilib-tools/roborio-team-number-setter/images/roborioteamnumbersetter.png + :alt: roboRIO Team Number Setter tool. + +The roboRIO Team Number Setter is a cross-platform utility that can be used to set the team number on the roboRIO. It is an alternative to the roboRIO imaging tool for setting the team number. For more information see the :ref:`roboRIO Team Number Setter section `. diff --git a/source/docs/hardware/hardware-basics/can-wiring-basics.rd b/source/docs/hardware/hardware-basics/can-wiring-basics.rd new file mode 100644 index 0000000000..a8340e3d0d --- /dev/null +++ b/source/docs/hardware/hardware-basics/can-wiring-basics.rd @@ -0,0 +1,24 @@ +CAN Wiring Basics +================= + +:term:`CAN` is a two wire network that is designed to facilitate communication between multiple devices on your robot. It is recommended that CAN on your robot follow a "daisy-chain" topology. This means that the CAN wiring should usually start at your roboRIO and go into and out of each device successively until finally ending at the :term:`PDP`. + +.. image:: images/can-wiring-basics/daisychain.png + +Standard Wiring +--------------- + +CAN is generally wired with yellow and green wire with yellow acting as the CAN-High and green as the CAN-Low signals. Many devices show this yellow and green color scheme to indicate how the wires should be plugged in. + +CAN wiring from the roboRIO to the PCM. + +.. image:: /docs/zero-to-robot/step-1/images/how-to-wire-a-simple-robot/pcm-can.jpg + +CAN wiring from the PCM to the PDP. + +.. image:: /docs/zero-to-robot/step-1/images/how-to-wire-a-simple-robot/pdp-can.jpg + +Termination +----------- + +It is recommended that the wiring starts at the roboRIO and ends at the PDP because the CAN network is required to be terminated by 120 :math:`\Omega` resistors and these are built into these two devices. The PDP ships with the CAN bus terminating resistor jumper in the "ON" position. It is recommended to leave the jumper in this position and place any additional CAN nodes between the roboRIO and the PDP (leaving the PDP as the end of the bus). If you wish to place the PDP in the middle of the bus (utilizing both pairs of PDP CAN terminals) move the jumper to the "OFF" position and place your own 120 :math:`\Omega` terminating resistor at the end of your CAN bus chain. diff --git a/source/docs/hardware/hardware-basics/index.rd b/source/docs/hardware/hardware-basics/index.rd new file mode 100644 index 0000000000..3418223b49 --- /dev/null +++ b/source/docs/hardware/hardware-basics/index.rd @@ -0,0 +1,14 @@ +Hardware - Basics +================= + +.. toctree:: + :maxdepth: 1 + + /docs/controls-overviews/control-system-hardware + wiring-best-practices + can-wiring-basics + wiring-pneumatics-pcm + wiring-pneumatics-ph + status-lights-ref + preemptive-troubleshooting + robot-battery diff --git a/source/docs/hardware/hardware-basics/preemptive-troubleshooting.rd b/source/docs/hardware/hardware-basics/preemptive-troubleshooting.rd new file mode 100644 index 0000000000..6e6bf1976c --- /dev/null +++ b/source/docs/hardware/hardware-basics/preemptive-troubleshooting.rd @@ -0,0 +1,161 @@ +.. include:: + +Robot Preemptive Troubleshooting +================================ + +.. note:: + + In *FIRST*\ |reg| Robotics Competition, robots take a lot of stress while driving around the field. It is important to make sure that connections are tight, parts are bolted securely in place and that everything is mounted so that a robot bouncing around the field does not break. + +Check Battery Connections +------------------------- + +.. image:: images/preemptive-troubleshooting/preCheckBatt.png + :alt: Trying to wiggle the battery terminal by hand. + :width: 500 + +The tape that should be covering the battery connection in these examples has been removed to illustrate what is going on. On your robots, the connections should be covered. + +Wiggle battery harness connector. Often these are loose because the screws loosen, or sometimes the crimp is not completely closed. You will only catch the really bad ones though because often the electrical tape stiffens the connection to a point where it feels stiff. Using a voltmeter or Battery Beak will help with this. + +Apply considerable force onto the battery cable at 90 degrees to try to move the direction of the cable leaving the battery, if successful the connection was not tight enough to begin with and it should be redone. This :ref:`article ` has more detailed battery information. + +Securing the Battery to the Robot +--------------------------------- + +.. image:: images/preemptive-troubleshooting/preCheckConnecc.png + :alt: Disconnected battery of a robot mid match. + :width: 350 + +In almost every event we see at least one robot where a not properly secured battery connector (the large Anderson) comes apart and disconnects power from the robot. This has happened in championship matches on the Einstein and everywhere else. Its an easy to ensure that this doesn't happen to you by securing the two connectors by wrapping a tie wrap around the connection. 10 or 12 tie wraps for the peace of mind during an event is not a high price to pay to guarantee that you will not have the problem of this robot from an actual event after a bumpy ride over a defense. Also, secure your battery to the chassis with hook and loop tape or another method, especially in games with rough defense, obstacles or climbing. + +Securing the Battery Connector & Main Power Leads +------------------------------------------------- + +A loose robot-side battery connector (the large Anderson SB) can allow the main power leads to be tugged when the battery is replaced. If the main power leads are loose, that "tug" can get all the way back to the crimp lugs attached to the 120 Amp Circuit Breaker or Power Distribution Panel (PDP), bend the lug, and over time cause the lug end to break from fatigue. Putting a couple tie wraps attaching the main power leads to the chassis and bolting down the robot-side battery connector can prevent this, as well as make it easier to connect the battery. + +Main Breaker (120 Amp Circuit Breaker) +-------------------------------------- + +.. note:: Ensure nuts are tightened firmly and the breaker is attached to a rigid element. + +.. image:: images/preemptive-troubleshooting/preCheckBreaker-1.png + :alt: Applying a twisting force to the first cable on the breaker. + :width: 350 + +.. image:: images/preemptive-troubleshooting/preCheckBreaker-2.png + :alt: Applying a twisting force to the second cable on the breaker. + :width: 350 + +Apply a strong twisting force to try to rotate the crimped lug. If the lug rotates then the nut is not tight enough. After tightening the nut, retest by once again trying to rotate the lug. + +The original nut has a star locking feature, which can wear out over time: these may require checking every few matches, especially if your robot-side battery connector is not attached to the chassis. + +The nut is normally a relatively uncommon 1/4-28 thread: ensure this is correct if the nut is replaced. + +Because the metal stud is just molded into the case, every once in awhile you may break off the stud. Don't stress, just replace the assembly. + +When subjected to multiple competition seasons, the Main Breaker is susceptible to fatigue damage from vibration and use, and can start opening under impact. Each time the thermal fuse function is triggered, it can become progressively easier to trip. Many veteran teams start each season with a fresh main breaker, and carry spares. + +Power Distribution Panel (PDP) +------------------------------ + +.. image:: images/preemptive-troubleshooting/pdp-bolts.png + :alt: Battery terminals on the PDP. + :width: 500 + +Make sure that split washers were placed under the PDP screws, but it is not easy to visually confirm, and sometimes you can’t. You can check by removing the case. +Also if you squeeze the red and black wires together, sometimes you can catch the really lose connections. + +Tug Testing +----------- + +.. image:: images/preemptive-troubleshooting/preCheckTug-1.png + :alt: Tug test on the roboRIO power. + :width: 350 + +.. image:: images/preemptive-troubleshooting/preCheckTug-2.png + :alt: Tug test on the connectors at the bottom of the PDP. + :width: 350 + +The Weidmuller contacts for power, compressor output, roboRIO power connector, and radio power are important to verify by tugging on the connections as shown. Make sure that none of the connections pull out. + +Look for possible or impending shorts with Weidmuller connections that are close to each other, and have too-long wire-lead lengths (wires that are stripped extra long). + +Spade connectors can also fail due to improper crimps, so tug-test those as well. + +Blade Fuses +----------- + +Be sure to place the 20A fuse (yellow) on the left and the 10A fuse (red) on the right. + +.. image:: images/preemptive-troubleshooting/pdp-blade-fuses.svg + :alt: PDP diagram showing the bottom connections and fuses. + :width: 600 + +.. image:: images/preemptive-troubleshooting/blade-fuses.png + :alt: Bottom of the PDP focusing on the 20A and 10A fuses. + :width: 600 + +.. warning:: Take care to ensure fuses are fully seated into the fuse holders. The fuses should descend at least as far as the figure below (different brand fuses have different lead lengths). It should be nearly impossible to remove the fuse with bare hands (without the use of pliers). If this is not properly done, the robot/radio may exhibit intermittent connectivity issues. + +If you can remove the blade fuses by hand then they are not in completely. Make sure that they are completely seated in the PDP so that they don't pop out during robot operation. + +roboRIO swarf +------------- + +Swarf is fine chips or filings of stone, metal, or other material produced by a machining operation. Often modifications must be made to a robot while the control system parts are in place. The circuit board for the roboRIO is conformally coated, but that doesn't absolutely guarantee that metal chips won't short out traces or components inside the case. In this case, you must exercise care in making sure that none of the chips end up in the roboRIO or any of the other components. In particular, the exposed 3 pin headers are a place where chips can enter the case. A quick sweep through each of the four sides with a flashlight is usually sufficient to find the really bad areas of infiltration. + +Radio Barrel Jack +----------------- + +Make sure the correct barrel jack is used, not one that is too small and falls out for no reason. This isn’t common, but ask an :term:`FTA` and every once in awhile a team will use some random barrel jack that is not sized correctly, and it falls out in a match on first contact. + +Ethernet Cable +-------------- + +If the RIO to radio ethernet cable is missing the clip that locks the connector in, get another cable. This is a common problem that will happen several times in every competition. Make sure that your cables are secure. The clip often breaks off, especially when pulling it through a tight path, it snags on something then breaks. + +Loose Cables +------------ + +Cables must be tightened down, particularly the radio power and ethernet cable. The radio power cables don’t have a lot of friction force and will fall out (even if it is the correct barrel) if the weight of the cable-slack is allowed to swing freely. + +Ethernet cable is also pretty heavy, if it’s allowed to swing freely, the plastic clip may not be enough to hold the ethernet pin connectors in circuit. + +Reproducing Problems in the Pit +------------------------------- + +Beyond the normal shaking of cables whilst the robot is powered and tethered, it is suggested that one side of the robot be picked up and dropped. Driving on the field, especially against defenders, will often be very violent, and this helps makes sure nothing falls out. It is better for the robot to fail in the pits rather than in the middle of a match. + +When doing this test it’s important to be ethernet tethered and not USB tethered, otherwise you are not testing all of the critical paths. + +Check Firmware and Versions +--------------------------- + +Robot inspectors do this, but you should do it as well, it helps robot inspectors out and they appreciate it. And it guarantees that you are running with the most recent, bug fixed code. You wouldn't want to lose a match because of an out of date piece of control system software on your robot. + +Driver Station Checks +--------------------- + +We often see problems with the Drivers Station. You should: + +- ALWAYS bring the laptop power cable to the field, it doesn’t matter how good the battery is, you are allowed to plug in at the field. +- Check the power and sleep settings, turn off sleep and hibernate, screen savers, etc. +- Turn off power management for USB devices (dev manager) +- Turn off power management for ethernet ports (dev manager) +- Turn off windows defender +- Turn off firewall +- Close all apps except for DS/Dashboard when out on the field. +- Verify that there is nothing unnecessary running in the application tray in the start menu (bottom right side) + +Handy Tools +----------- + +.. image:: images/preemptive-troubleshooting/tools.png + :alt: A Wago screwdriver and flashlight. + :width: 500 + +There never seems to be enough light inside robots, at least not enough to scrutinize the critical connection points, so consider using a handheld LED flashlight to inspect the connections on your robot. They're available from home depot or any hardware/automotive store. + +A WAGO tool is nice tool for redoing Weidmuller connections with stranded wires. Often I’ll do one to show the team, and then have them do the rest using the WAGO tool to press down the white-plunger while they insert the stranded wire. The angle of the WAGO tool makes this particularly helpful. diff --git a/source/docs/hardware/hardware-basics/robot-battery.rd b/source/docs/hardware/hardware-basics/robot-battery.rd new file mode 100644 index 0000000000..30152315f8 --- /dev/null +++ b/source/docs/hardware/hardware-basics/robot-battery.rd @@ -0,0 +1,200 @@ +.. include:: + +Robot Battery Basics +==================== + +The power supply for an FRC\ |reg| robot is a single 12V 18Ah SLA (Sealed Lead Acid) non-spillable battery, capable of briefly supplying over 180A and arcing over 500A when fully charged. The Robot Battery assembly includes the :term:`COTS` battery, lead cables with contacts, and Anderson SB connector. Teams are encouraged to have multiple Robot Batteries. + +COTS Battery +------------ + +The Robot Rules in the Game Manual specify a COTS non-spillable sealed lead acid battery meeting specific criteria, and gives examples of legal part numbers from a variety of vendors. + +Battery Safety & Handling +------------------------- + +A healthy battery is **always** "On" and the terminals are **always** energized. If the polarities short together - for example, a wrench or aerosol can falls and bridges the gap between two bare terminals - all the stored energy will be released in a dangerous arc. This risk drives a wide range of best practices, such as covering terminals in storage, only uncovering and working on one terminal or polarity at a time, keeping SB contacts fully inserted in connectors, etc. + +**Do *NOT* carry a battery assembly by the cables**, and always avoid pulling by them. Pulling on batteries by the cables will begin to damage the lugs, tabs, and the internal connection of the tab. Over time, fatigue damage can add up until the entire tab tears out of the housing! Even if it isn't clearly broken, internal fatigue damage can increase the battery internal resistance, prematurely wearing out the battery. The battery will not be able to provide the same amount of current with increased internal resistance or if the :ref:`connectors are loose `. + +.. image:: images/robot-battery/broken-terminal.png + :alt: One terminal of an FRC battery fully detached from the battery. + +Dropping the batteries can bend the internal plates and cause performance issues, create bulges, or even crack the battery case open. While most FRC batteries use Absorbent Glass Mat [AGM] or Gel technology for safety and performance, when a cell is punctured it may still leak a small amount of battery acid. This is one of the reasons FIRST recommends teams have a battery spill kit available. + +Finally, certain older battery chargers without "maintenance mode" features can *overcharge* the battery, resulting in boiling off some of the battery acid. + +.. image:: images/robot-battery/boiled.jpg + :alt: An FRC battery that was boiled by a high current dumb charger. + +Damaged batteries should be safely disposed of as soon as possible. All retailers that sell large SLA batteries, like car batteries, should be able to dispose of it for you. They may charge a small fee, or provide a small "core charge refund", depending on your state law. + +.. danger:: **DO NOT** attempt to "repair" damaged or non-functional batteries. + +Battery Construction & Tools +---------------------------- + +Battery Leads +^^^^^^^^^^^^^ + +Battery leads must be copper, minimum size (cross section) 6 AWG (16mm2, 7 SWG) and maximum length 12", color coded for polarity, with an Anderson SB connector. Standard 6AWG copper leads with Pink/Red SB50 battery leads often come in the Kit of Parts and are sold by FRC vendors. + +Lead Cables +~~~~~~~~~~~ + +Tinned, annealed, or coated copper is allowed. Do not use CCA (copper clad aluminum), aluminum, or other non-copper base metal. The conductor metal is normally printed on the outside of the insulation with the other cable ratings. + +Wire size 6AWG is sufficient for almost all robots and fits standard SB50 contacts. A small number of teams adopt larger wire sizes for marginal performance benefits. + +Higher strand count wire (sometimes sold as "Flex" or "welding wire") has a smaller bend radius, which makes it easier to route, and a higher fatigue limit. There is no strand count requirement, but 84/25 (84 strand "flex" hookup wire) and 259/30 (259 strand "welding wire") will both be *much* easier to work with than 19/0.0372 (19 strand hookup wire). + +The insulation must be color-coded per the Game Manual: the +12Vdc wire must be red, white, brown, yellow, or black w/stripe and the ground wire (return wire) must be black or blue. There is no explicit insulation temperature rating requirement, but any blackened or damaged insulation means the wire needs to be replaced: off hand, 105C is plenty and lower will work for almost all robots. There is no insulation voltage rating requirement, lower is better for thinner insulation. + +SB Connector +~~~~~~~~~~~~ + +The Anderson SB Connector may be the standard Pink/Red SB50, or another Anderson SB connector. Teams are *STRONGLY* recommended to use the Pink/Red SB50 for interoperability: the other colors and sizes of housings will not intermate, and you will be unable to borrow batteries or chargers. + +Follow manufacturer's instructions to crimp contacts and assemble the leads into Anderson SB connectors. A small flathead screwdriver can help to insert the contacts (push on the contact, not on the wire insulation), or it can help to disengage the internal latch if the contact is in the wrong slot or upside down. + +Battery Lugs +^^^^^^^^^^^^ + +Compression lugs ("crimp lugs") for #10 bolt (or M5) battery tabs (~0.2" or ~5mm hole diameter) are available online and through electrical supply houses, sold by the accepted wire sizes in AWG (or mm2) and post diameter ("bolt size", "hole diameter"). Higher end vendors will also distinguish between Standard (~19) and Flex (>80) strand counts in their lug catalogs. Some vendors also offer right angle lugs, in addition to more common straight styles. Follow manufacturer's instructions to crimp the lugs. + +Screw terminal lugs are legal, but not recommended. If using screw terminal lugs, use the correct tip size screwdriver to tighten the terminal. Check the terminal tightness frequently because they may loosen over time. + +Battery Lead Lug To Post Connection +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A #10 or M5 nut & bolt connect the battery lead lug to the battery tab. + +.. warning:: The lug and tab must directly contact, copper to copper: do not put a washer of any kind separating them. + +.. image:: images/robot-battery/tab-contact.jpg + :alt: One terminal of an FRC battery with socket head bolt and nylon locking (nylock) nut. + +Some batteries come with tab bolts in the package: they may be used, or replaced with stronger alloy steel bolts. It is a good idea to add a functional lock washer, such as a #10 star washer or a nordlock washer system, in addition to a nylon locking ("nylock") nut. Only use one style of lock washer in each connection. Even if the manufacturer provides split ring lock washers in the package, you are not required to use them. + +.. image:: images/robot-battery/loose-nordlock.jpg + :alt: One terminal of an FRC battery with socket head bolt, nordlock locking nuts, and nylon locking (nylock) nut. + +These connections must be very tight for reliability. Any movement of the lug while in operation may interrupt robot power, resulting in robot reboots and field disconnections lasting 30 seconds or more. + +This connection must also be completely covered for electrical safety; electrical tape will work, but heatshrink that fits over the entire connection is recommended. High shrink ratios (minimum 3:1, recommend 4:1) will make it easier to apply the heatshrink. Adhesive lined heat shrink is allowed. Be sure *all* the copper is covered! Heat shrink must be "touched up" with electrical tape if some copper shows. + +.. image:: images/robot-battery/heatshrink.png + :alt: One terminal of an FRC battery fully covered in heatshrink. + +Battery Chargers +^^^^^^^^^^^^^^^^ + +There are many good COTS "smart" battery chargers designed for 12V SLA batteries, rated for 6A or less per battery, with 'maintenance mode' features. Chargers rated over 6A are not allowed in FRC pits. + +Chargers used at competition are required to use Anderson SB connectors. Attaching a COTS SB connector battery lead to the charger leads using appropriately sized wire nuts or screw terminals is fast and simple (be sure to cover any exposed copper with heat shrink or electrical tape). SB Connector Contacts are also available for smaller wire sizes, if the team has crimping capability. + +.. warning:: After attaching the SB, double check the charger polarities with a multimeter before plugging in the first battery. + +Some FRC vendors sell chargers with red SB50 connectors pre-attached. + +Battery Evaluation Tools +^^^^^^^^^^^^^^^^^^^^^^^^ + +**Battery Charger** + +If your battery charger has Maintenance Mode indicator, such as a GREEN LED, you can use that indicator to tell you whether you are READY. Some chargers will cycle between "CHARGING" and "READY" periodically. This is a "maintenance" behavior, sometimes associated with the battery cooling off and being able to accept more charge. + +**Driver Station Display and Log** + +When the robot is plugged in and connected to the driver station laptop, the battery voltage is displayed on the NI Driver Station software. + +After you finish a driving session, you can :ref:`review the battery voltage in the Log Viewer. ` + +Hand-held **Voltmeter** or **Multimeter** + +A voltage reading from probes on the SB connector of a disconnected battery will give you a snapshot of what the Voc (Voltage open circuit, or "float voltage") is in the "Unloaded" state. In general the Voc is not a recommended method for understanding battery health: the open circuit voltage is not as useful as the combination of internal resistance and voltages at specific loads provided by a Load Tester (or Battery Analyzer). + +**Load Tester** + +A battery load tester can be used as a quick way to determine the detailed readiness of a battery. It may provide information like: open-load voltage, voltage under load, internal resistance, and state of charge. These metrics can be used to quickly confirm that a battery is ready for a match and even help to identify some long term problems with the battery. + +.. image:: images/robot-battery/beak.png + :alt: Output screen of a common load tester showing properties of the battery. + +Ideal internal resistance should be less than 0.015 Ohms. The manufacturer specification for most batteries is 0.011 Ohms. If a battery gets higher than 0.020 Ohms it is a good idea to consider not using that battery for competition matches. + +If a battery shows significantly lower voltages at the higher test current loads, it may not be done charging, or it may need to be retired. + +Understanding Battery Voltages +------------------------------ + +A "12V battery" is anything but 12.0V. + +Fully charged, a battery can be anywhere from 12.7 to 13.5 volts open circuit (Voc). Open circuit voltage is measured with *nothing* connected. + +Once a load (like a robot) is connected, and any amount of current is flowing, the battery voltage will drop. So if you check a battery with a Voltmeter, and it reads 13.2, and then connect it to your robot and power on, it will read lower, maybe 12.9 on the Driver Station display. Those numbers will vary with every battery and specific robot, see Characterization below. Once your robot starts running, it will pull more current, and the voltage will drop further. + +Batteries reading 12.5V on an idle robot should be swapped and charged before a match. Always swap the batteries before the robot starts reaching brownout safety thresholds (dwelling at low voltages on the Driver Station display), as frequently entering low voltage ranges risks permanent battery damage; this behavior can happen at a variety of Voc states depending on battery health, battery manufacturer, and robot design. The battery State of Charge should be kept over 50% for battery longevity. + +Battery voltage and current also depends on temperature: cool batteries are happy batteries. + +Battery Characterization +^^^^^^^^^^^^^^^^^^^^^^^^ + +A battery analyzer can be used to give a detailed inspection and comparison of battery performance. + +.. image:: images/robot-battery/cba-graph.jpg + :alt: Graph from a common battery analyzer plotting volts and AmpHrs for many different batteries. + +It will provide graphs of battery performance over time. This test takes significant time (roughly two hours) so it is less suited to testing during competition. It is recommended to run this test on each battery every year to monitor and track its performance. This will determine how it should be used: matches, practice, testing, or disposed of. + +At the standard 7.5 amps test load, competition batteries should have at least a 11.5 amp hour rating. Anything less than that should only be used for practice or other less demanding use cases. + +Battery Longevity +^^^^^^^^^^^^^^^^^ + +A battery is rated for about 1200 normal charge/recharge cycles. The high currents required for an FRC match reduce that lifespan to about 400 cycles. These cycles are intended to be relatively low discharge, from around 13.5 down to 12 or 12.5 volts. Deep cycling the battery (running it all the way down) will damage it. + +Batteries last the longest if they are kept fully charged when not in use, either by charging regularly or by use of a maintenance charger. Batteries drop roughly 0.1V every month of non-use. + +Batteries need to be kept away from both extreme heat and cold. This generally means storing the batteries in a climate controlled area: a classroom closet is usually fine, a parking lot shipping container is more risky. + +Battery Best Practices +---------------------- + +- Only use a charged battery for competition matches. If you are in a situation where you have run out of charged batteries, please ask a veteran team for help! Nobody wants to see a robot dead on the field (:ref:`brownout `) due to a bad or uncharged battery. + +- Teams are strongly recommended to use properly rated tools and stringent quality control practices for crimping processes (ask local veteran teams or a commercial electrician for help), or use vendor-made Battery Leads. + +- Wait for batteries to cool after the match before recharging: the case should not be warm to the touch, fifteen minutes is usually plenty. + +- Teams should consider purchasing several new batteries each year to help keep their batteries fresh. Elimination matches can require many batteries and there may not be enough time to recharge. + +.. image:: images/robot-battery/battery-cart.jpg + :alt: A wooden bookcase like cart for storing and charging batteries. + +- A multi bank battery charger allows you to charge more than one battery at a time. Many teams build a robot cart for their batteries and chargers allowing for easy transport and storage. + +- It is a good idea to permanently identify each battery with at least: team number, year, and a unique identifier. + +- Teams may also want to use something removable (stickers, labeling machine etc.) to identify what that battery should be used for based on its performance data and when the last analyzer test was run. + +.. image:: images/robot-battery/battery-flag.jpg + :alt: A battery flag is just a small piece of plastic that fits in the battery connector. + +- Using battery flags (a piece of plastic placed in the battery connector) is a common way to indicate that a battery has been charged. Battery flags can also be easily 3D printed. + +- Handles for SB50 contacts can be purchased or 3D printed to help avoid pulling on the leads while connecting or disconnecting batteries. Do not use these handles to carry the weight of the battery. + +.. image:: images/robot-battery/sb50-handle.png + :alt: A plastic handle bolted on to an assembled SB50 connector. + +- Some teams sew battery carrying straps from old seatbelts or other flat nylon that fit around the battery to help prevent carrying by leads. + +.. image:: images/robot-battery/battery-strap.png + :alt: An example showing a 2" wide nylon strap, wrapped around the battery and sewn into a loop. + +- Cable tie edge clips can be used with 90 degree crimp lugs to strain relieve battery leads. + +.. image:: images/robot-battery/edge-clip.png + :alt: An example showing edge clips with zipties holding leads on a battery. diff --git a/source/docs/hardware/hardware-basics/status-lights-ref.rd b/source/docs/hardware/hardware-basics/status-lights-ref.rd new file mode 100644 index 0000000000..e69de29bb2 From 1c9fae26e0fb1b01218b2fb9481a5d2ac59daec4 Mon Sep 17 00:00:00 2001 From: Falon <47285315+falOn-Dev@users.noreply.github.com> Date: Sat, 7 Sep 2024 01:43:41 -0400 Subject: [PATCH 15/19] Docstring + Formatting --- scripts/check_codeblock_coverage.py | 28 +++++++++++++++++++++------- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/scripts/check_codeblock_coverage.py b/scripts/check_codeblock_coverage.py index efbda8b12b..b7554a26da 100644 --- a/scripts/check_codeblock_coverage.py +++ b/scripts/check_codeblock_coverage.py @@ -1,3 +1,18 @@ +""" +This script checks the code block coverage in .rst files in a specified directory. +It counts the number of code blocks for each language and outputs the coverage percentage for each language. +If the verbose flag is set, it also outputs detailed information about missing code blocks. + +Arguments for the script: +--dir: The directory to search for .rst files (required) +--verbose: Include detailed information about missing code blocks, as well as output to file rather than terminal (optional, default=False) +--output: The path to the output file (optional, default="output.txt") +--langs: The languages to check for (optional, default=["java", "python", "c++"]) + +Example usage: python check_codeblock_coverage.py --dir=docs --verbose --output=missing_code_blocks.txt +Example usage: python check_codeblock_coverage.py --dir=docs --langs=java python c++ +""" + import sys import os import re @@ -51,6 +66,7 @@ def is_codeblock(line: str) -> bool: """ return line.startswith(".. tab-set-code::") or line.startswith(".. tab-set::") + def generate_language_regex(langs: list[str]) -> str: """ Generates a regex pattern to match the specified languages. @@ -63,6 +79,7 @@ def generate_language_regex(langs: list[str]) -> str: """ return f"(`{{3}}|:language: )({'|'.join(langs)})".replace("+", r"\+") + def get_blocks_from_rst_file(file: str, langs: list[str]) -> list[CodeBlock]: """ Extracts code blocks from a given .rst file. @@ -86,12 +103,10 @@ def get_blocks_from_rst_file(file: str, langs: list[str]) -> list[CodeBlock]: langs = [] else: if line.startswith(" ") or line.startswith("\t"): - lang = re.search( - lang_regex, line.lower() - ) + lang = re.search(lang_regex, line.lower()) if lang is not None: langs.append(lang.group(2)) - + if langs != []: blocks.append(CodeBlock(start=block_start, file=file, langs=langs)) @@ -168,11 +183,10 @@ def main(): parser.add_argument( "--langs", nargs="+", - default=['java', 'python', 'c++'], + default=["java", "python", "c++"], help="Languages to check for", ) - # Parse the command line arguments args = parser.parse_args() @@ -193,4 +207,4 @@ def main(): if __name__ == "__main__": - main() \ No newline at end of file + main() From 64ef5c70da8fe902f1d46e9ff1aecb91170c0517 Mon Sep 17 00:00:00 2001 From: Falon <47285315+falOn-Dev@users.noreply.github.com> Date: Sat, 7 Sep 2024 12:48:49 -0400 Subject: [PATCH 16/19] Revert "Left in debug statement on accident" This reverts commit bd3b68a068b6ff2949ba2af17229e74d490842c1. --- scripts/check_codeblock_coverage.py | 2 + .../contributing/frc-docs/translations.rd | 47 --- source/docs/contributing/wpilib/index.rd | 39 --- .../control-system-hardware.rd | 329 ------------------ .../control-system-software.rd | 160 --------- .../hardware-basics/can-wiring-basics.rd | 24 -- source/docs/hardware/hardware-basics/index.rd | 14 - .../preemptive-troubleshooting.rd | 161 --------- .../hardware/hardware-basics/robot-battery.rd | 200 ----------- .../hardware-basics/status-lights-ref.rd | 0 10 files changed, 2 insertions(+), 974 deletions(-) delete mode 100644 source/docs/contributing/frc-docs/translations.rd delete mode 100644 source/docs/contributing/wpilib/index.rd delete mode 100644 source/docs/controls-overviews/control-system-hardware.rd delete mode 100644 source/docs/controls-overviews/control-system-software.rd delete mode 100644 source/docs/hardware/hardware-basics/can-wiring-basics.rd delete mode 100644 source/docs/hardware/hardware-basics/index.rd delete mode 100644 source/docs/hardware/hardware-basics/preemptive-troubleshooting.rd delete mode 100644 source/docs/hardware/hardware-basics/robot-battery.rd delete mode 100644 source/docs/hardware/hardware-basics/status-lights-ref.rd diff --git a/scripts/check_codeblock_coverage.py b/scripts/check_codeblock_coverage.py index b7554a26da..beb7ab17a0 100644 --- a/scripts/check_codeblock_coverage.py +++ b/scripts/check_codeblock_coverage.py @@ -190,6 +190,8 @@ def main(): # Parse the command line arguments args = parser.parse_args() + print(generate_language_regex(args.langs)) + # Get all .rst files from the specified directory files = get_all_rst_files(dir=args.dir) blocks = [] diff --git a/source/docs/contributing/frc-docs/translations.rd b/source/docs/contributing/frc-docs/translations.rd deleted file mode 100644 index bd1ec93e74..0000000000 --- a/source/docs/contributing/frc-docs/translations.rd +++ /dev/null @@ -1,47 +0,0 @@ -Translations -============ - -frc-docs supports translations using the web-based `Transifex `__ utility. frc-docs has been translated into Spanish - Mexico (es_MX), French - Canada (fr_CA) and Turkish - Turkey (tr_TR). Chinese - China (zh_CN), Hebrew - Israel (he_IL), and Portuguese - Brazil (pt_BR) have translations in progress. Translators that are fluent in *both* English and one of the specified languages would be greatly appreciated to contribute to the translations. Even once a translation is complete, it needs to be updated to keep up with changes in frc-docs. - -Workflow --------- - -Here are some steps to follow for translating frc-docs. - -1. Sign up for `Transifex `__ and ask to join the `frc-docs project `__, and request access to the language you'd like to contribute to. -2. Join GitHub `discussions `__! This is a direct means of communication with the WPILib team. You can use this to ask us questions in a fast and streamlined fashion. -3. You may be contacted and asked questions involving contributing languages before being granted access to the frc-docs translation project. -4. Translate your language! - -Links ------ - -Links must be preserved in their original syntax. To translate a link, you can replace the TRANSLATE ME text (this will be replaced with the English title) with the appropriate translation. - -An example of the original text may be - -.. code-block:: text - - For complete wiring instructions/diagrams, please see the :doc:`Wiring the FRC Control System Document `. - -where the ``Wiring the FRC Control System Document`` then gets translated. - -.. code-block:: text - - For complete wiring instructions/diagrams, please see the :doc:`TRANSLATED TEXT `. - -Another example is below - -.. code-block:: text - - For complete wiring instructions/diagrams, please see the :ref:`TRANSLATED TEXT ` - -Publishing Translations ------------------------ - -Translations are pulled from Transifex and published automatically each day. - -Accuracy --------- - -Translations should be accurate to the original text. If improvements to the English text can be made, open a PR or issue on the `frc-docs `__ repository. These can then get translated on merge. diff --git a/source/docs/contributing/wpilib/index.rd b/source/docs/contributing/wpilib/index.rd deleted file mode 100644 index e12cdc7621..0000000000 --- a/source/docs/contributing/wpilib/index.rd +++ /dev/null @@ -1,39 +0,0 @@ -.. include:: - -Developing with allwpilib -========================= - -.. important:: This document contains information for developers *of* WPILib. This is not for programming FRC\ |reg| robots. - -This is a list of links to the various documentation for the `allwpilib `__ repository. - -Quick Start ------------ - -Below is a list of instructions that guide you through cloning, building, publishing and using local allwpilib binaries in a robot project. This quick start is not intended as a replacement for the information that is further listed in this document. - -* Clone the repository with ``git clone https://github.com/wpilibsuite/allwpilib.git`` -* Build the repository with ``./gradlew build`` or ``./gradlew build --build-cache`` if you have an internet connection -* Publish the artifacts locally by running ``./gradlew publish`` -* `Update your robot project's `__ ``build.gradle`` `to use the artifacts `__ - -Core Repository ---------------- -.. toctree:: - :maxdepth: 1 - - Overview - Styleguide & wpiformat - Building with CMake - Using Development Builds - Maven Artifacts - Contributor Guidelines - -NetworkTables -------------- - -.. toctree:: - :maxdepth: 1 - - NetworkTables 4 Protocol Spec - NetworkTables 3 Protocol Spec diff --git a/source/docs/controls-overviews/control-system-hardware.rd b/source/docs/controls-overviews/control-system-hardware.rd deleted file mode 100644 index cacc1d3905..0000000000 --- a/source/docs/controls-overviews/control-system-hardware.rd +++ /dev/null @@ -1,329 +0,0 @@ -.. include:: - -Hardware Component Overview -=========================== - -The goal of this document is to provide a brief overview of the hardware components that make up the FRC\ |reg| Control System. Each component will contain a brief description of the component function and a link to more documentation. - -.. note:: For wiring instructions/diagrams, please see the :doc:`Wiring the FRC Control System ` document. - -Overview of Control System --------------------------- - -.. tab-set:: - .. tab-item:: REV - :sync: rev - - .. figure:: images/frc-control-system-layout-rev.svg - :alt: Layout of all popular components of the control system including REV Control System Components - :width: 500 - - Diagram courtesy of FRC\ |reg| Team 3161 and Stefen Acepcion. - - .. tab-item:: CTRE - :sync: ctre - - .. figure:: images/frc-control-system-layout.svg - :alt: Layout of all of the core components of the control system and how they are connected. - :width: 500 - - Diagram courtesy of FRC\ |reg| Team 3161 and Stefen Acepcion. - -NI roboRIO ----------- - -.. image:: images/control-system-hardware/roborio.png - :alt: NI roboRIO - :width: 500 - -The :ref:`NI-roboRIO ` is the main robot controller used for FRC. The roboRIO serves as the "brain" for the robot running team-generated code that commands all of the other hardware. - -CTRE Power Distribution Panel ------------------------------ - -.. image:: images/control-system-hardware/power-distribution-panel.png - :alt: CTRE Power Distribution Panel - :width: 500 - -The :ref:`CTRE Power Distribution Panel ` (PDP) is designed to distribute power from a 12VDC battery to various robot components through auto-resetting circuit breakers and a small number of special function fused connections. The PDP provides 8 output pairs rated for 40A continuous current and 8 pairs rated for 30A continuous current. The PDP provides dedicated 12V connectors for the roboRIO, as well as connectors for the Voltage Regulator Module and Pneumatics Control Module. It also includes a CAN interface for logging current, temperature, and battery voltage. For more detailed information, see the `PDP User Manual `__. - -REV Power Distribution Hub --------------------------- - -.. image:: images/control-system-hardware/power-distribution-hub.png - :alt: REV Power Distribution Hub - :width: 500 - -The `REV Power Distribution Hub `__ (PDH) is designed to distribute power from a 12VDC battery to various robot components. The PDH features 20 high-current (40A max) channels, 3 low-current (15A max), and 1 switchable low-current channel. The Power Distribution Hub features toolless latching WAGO terminals, an LED voltage display, and the ability to connect over CAN or USB-C to the REV Hardware Client for real-time telemetry. - -CTRE Voltage Regulator Module ------------------------------ - -.. image:: images/control-system-hardware/voltage-regulator-module.png - :alt: CTRE Voltage Regulator Module - :width: 500 - -The CTRE Voltage Regulator Module (VRM) is an independent module that is powered by 12 volts. The device is wired to a dedicated connector on the PDP. The module has multiple regulated 12V and 5V outputs. The purpose of the VRM is to provide regulated power for the robot radio, custom circuits, and IP vision cameras. For more information, see the `VRM User Manual `__. - -REV Radio Power Module ----------------------- - -.. image:: images/control-system-hardware/radio-power-module.png - :alt: REV Radio Power Module - :width: 500 - -The `REV Radio Power Module `__ is designed to keep one of the most critical system components, the OpenMesh WiFi radio, powered in the toughest moments of the competition. The Radio Power Module eliminates the need for powering the radio through a traditional barrel power jack. Utilizing 18V Passive POE with two socketed RJ45 connectors, the Radio Power Module passes signal between the radio and roboRIO while providing power directly to the radio. After connecting the radio and roboRIO, easily add power to the Radio Power Module by wiring it to the low-current channels on the Power Distribution Hub utilizing the color coded push button WAGO terminals. - -OpenMesh OM5P-AN or OM5P-AC Radio ---------------------------------- - -.. image:: images/control-system-hardware/openmesh-radio.png - :alt: OpenMesh OM5P-AN or OM5P-AC Radio - :width: 500 - -Either the OpenMesh OM5P-AN or `OpenMesh OM5P-AC `__ wireless radio is used as the robot radio to provide wireless communication functionality to the robot. The device can be configured as an Access Point for direct connection of a laptop for use at home. It can also be configured as a bridge for use on the field. The robot radio should be powered by one of the 12V/2A outputs on the VRM and connected to the roboRIO controller over Ethernet. For more information, see :ref:`Programming your Radio `. - -The OM5P-AN `is no longer available for purchase `__. The OM5P-AC is slightly heavier, has more cooling grates, and has a rough surface texture compared to the OM5P-AN. - -120A Circuit Breaker --------------------- - -.. image:: images/control-system-hardware/circuit-breaker.png - :alt: 120A Circuit Breaker - :width: 500 - -The 120A Main Circuit Breaker serves two roles on the robot: the main robot power switch and a protection device for downstream robot wiring and components. The 120A circuit breaker is wired to the positive terminals of the robot battery and Power Distribution boards. For more information, please see the `Cooper Bussmann 18X Series Datasheet (PN: 185120F) `__ - -Snap Action Circuit Breakers ----------------------------- - -.. image:: images/control-system-hardware/snap-action-circuit-breaker.png - :alt: Snap Action Circuit Breakers to be inserted in the PDP. - :width: 500 - -The Snap Action circuit breakers, `MX5 series `__ and `VB3 Series `__, are used with the Power Distribution Panel to limit current to branch circuits. The ratings on these circuit breakers are for continuous current, temporary peak values can be considerably higher. - -Robot Battery -------------- - -.. image:: images/control-system-hardware/robot-battery.png - :alt: Robot Battery - :width: 500 - -The power supply for an FRC robot is a single 12V 18Ah Sealed Lead Acid (SLA) battery, capable of meeting the high current demands of an FRC robot. For more information, see the :ref:`Robot Battery page. ` - -.. note:: Multiple battery part numbers may be legal, consult the `FRC Manual `__ for a complete list. - -Robot Signal Light ------------------- - -.. tab-set:: - - .. tab-item:: Allen-Bradley - - .. figure:: images/control-system-hardware/rsl-allenbradley.jpg - :alt: Orange Robot Signal Light (Allen-Bradley) - :width: 500 - - Allen-Bradley 855PB-B12ME522 - - .. tab-item:: AndyMark - - .. figure:: images/control-system-hardware/rsl-andymark.png - :alt: Orange Robot Signal Light (AndyMark) - :width: 500 - - AndyMark am-3583 - -The Robot Signal Light (RSL) is required to be either Allen-Bradley 855PB-B12ME522 or AndyMark am-3583. It is directly controlled by the roboRIO and will flash when enabled and stay solid while disabled. - -CTRE Pneumatics Control Module ------------------------------- - -.. image:: images/control-system-hardware/pneumatics-control-module.png - :alt: CTRE Pneumatics Control Module - :width: 500 - -The :ref:`CTRE Pneumatics Control Module ` (PCM) contains all of the inputs and outputs required to operate 12V or 24V pneumatic solenoids and the on board compressor. The PCM contains an input for the pressure sensor and will control the compressor automatically when the robot is enabled and a solenoid has been created in the code. For more information see the `PCM User Manual `__. - -REV Pneumatic Hub ------------------ - -.. image:: images/control-system-hardware/pneumatic-hub.png - :alt: REV Pneumatic Hub - :width: 500 - -The `REV Pneumatic Hub `__ is a standalone module that is capable of switching both 12V and 24V pneumatic solenoid valves. The Pneumatic Hub features 16 solenoid channels which allow for up to 16 single-acting solenoids, 8 double-acting solenoids, or a combination of the two types. The user selectable output voltage is fully regulated, allowing even 12V solenoids to stay active when the robot battery drops as low as 4.75V. - -Digital and analog pressure sensor ports are built into the device, increasing the flexibility and feedback functionality of the pneumatic system. The USB-C connection on the Hub works with the REV Hardware Client, allowing users to test pneumatic systems without a need for an additional robot controller. - -Motor Controllers ------------------ - -There are a variety of different :ref:`motor controllers ` which work with the FRC Control System and are approved for use. These devices are used to provide variable voltage control of the brushed and brushless DC motors used in FRC. They are listed here in order of `usage `__. - -.. note:: 3rd Party CAN control is not supported from WPILib. See this section on :ref:`docs/software/can-devices/third-party-devices:Third-Party CAN Devices` for more information. - -Talon SRX -^^^^^^^^^ - -.. image:: images/control-system-hardware/talonsrx-motor-controller.png - :alt: Talon SRX - :width: 500 - -The `Talon SRX Motor Controller `__ is a "smart motor controller" from Cross The Road Electronics/VEX Robotics. The Talon SRX can be controlled over the CAN bus or :term:`PWM` interface. When using the CAN bus control, this device can take inputs from limit switches and potentiometers, encoders, or similar sensors in order to perform advanced control. For more information see the `Talon SRX User's Guide `__. - -Victor SPX -^^^^^^^^^^ - -.. image:: images/control-system-hardware/victor-spx-motor-controller.png - :alt: Victor SPX - :width: 500 - -The `Victor SPX Motor Controller `__ is a CAN or PWM controlled motor controller from Cross The Road Electronics/VEX Robotics. The device is connectorized to allow easy connection to the roboRIO PWM connectors or a CAN bus. The case is sealed to prevent debris from entering the controller. For more information, see the `Victor SPX User Guide `__. - -SPARK MAX Motor Controller -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. image:: images/control-system-hardware/spark-max-motor-controller.png - :alt: SPARK MAX Motor Controller - :width: 400 - -The `SPARK MAX Motor Controller `__ is an advanced brushed and brushless DC motor controller from REV Robotics. When using CAN bus or USB control, the SPARK MAX uses input from limit switches, encoders, and other sensors, including the integrated encoder of the REV NEO Brushless Motor, to perform advanced control modes. The SPARK MAX can be controlled over PWM, CAN or USB (for configuration/testing only). For more information, see the `SPARK MAX User's Manual `__. - -TalonFX Motor Controller -^^^^^^^^^^^^^^^^^^^^^^^^ - -.. image:: images/control-system-hardware/talonfx.png - :alt: TalonFX Motor Controller - :width: 500 - -The `TalonFX Motor Controller `__ is integrated into the Falcon 500 brushless motor. It features an integrated encoder and all of the smart features of the Talon SRX and more! For more information see the `Falcon 500 User Guide `__. - -SPARK Motor Controller -^^^^^^^^^^^^^^^^^^^^^^ - -.. image:: images/control-system-hardware/spark-motor-controller.png - :alt: SPARK Motor Controller - :width: 400 - -.. warning:: While this motor controller is still legal for FRC use, the manufacturer has discontinued this product. - -The `SPARK Motor Controller `__ from REV Robotics is an inexpensive brushed DC motor controller. The SPARK is controlled using the PWM interface. Limit switches may be wired directly to the SPARK to limit motor travel in one or both directions. - -Victor SP -^^^^^^^^^ - -.. image:: images/control-system-hardware/victor-sp-motor-controller.png - :alt: Victor SP - :width: 500 - -.. warning:: While this motor controller is still legal for FRC use, the manufacturer has discontinued this product. - -The `Victor SP Motor Controller `__ is a PWM motor controller from Cross The Road Electronics/VEX Robotics. The Victor SP has an electrically isolated metal housing for heat dissipation, making the use of the fan optional. The case is sealed to prevent debris from entering the controller. The controller is approximately half the size of previous models. - -Talon Motor Controller -^^^^^^^^^^^^^^^^^^^^^^ - -.. image:: images/control-system-hardware/talon-motor-controller.png - :alt: Talon Motor Controller - -.. warning:: While this motor controller is still legal for FRC use, the manufacturer has discontinued this product. - -The `Talon Motor Controller `__ from Cross the Road Electronics is a PWM controlled brushed DC motor controller with passive cooling. - -Victor 888 Motor Controller / Victor 884 Motor Controller -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. image:: images/control-system-hardware/victor-888-motor-controller.png - :alt: Victor 888 Motor Controller - :width: 400 - -.. warning:: While this motor controller is still legal for FRC use, the manufacturer has discontinued this product. - -The `Victor 884 `__ and `Victor 888 `__ motor controllers from VEX Robotics are variable speed PWM motor controllers for use in FRC. The Victor 888 replaces the Victor 884, which is also usable in FRC. - -Jaguar Motor Controller -^^^^^^^^^^^^^^^^^^^^^^^ - -.. image:: images/control-system-hardware/jaguar-motor-controller.png - :alt: Jaguar Motor Controller - :width: 500 - -.. warning:: While this motor controller is still legal for FRC use, the manufacturer has discontinued this product. - -The `Jaguar Motor Controller `__ from VEX Robotics (formerly made by Luminary Micro and Texas Instruments) is a variable speed motor controller for use in FRC. For FRC, the Jaguar may only be controlled using the PWM interface. - -DMC-60 and DMC-60C Motor Controller -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. image:: images/control-system-hardware/dmc-60c-motor-controller.png - :alt: DMC-60C Motor Controller - :width: 500 - -.. warning:: While this motor controller is still legal for FRC use, the manufacturer has discontinued this product. - -The DMC-60 is a PWM motor controller from Digilent. The DMC-60 features integrated thermal sensing and protection including current-foldback to prevent overheating and damage, and four multi-color LEDs to indicate speed, direction, and status for easier debugging. For more information, see the `DMC-60 reference manual `__ - -The DMC-60C adds CAN smart controller capabilities to the DMC-60 controller. Due to the manufacturer discontinuing this product, the DMC-60C is only usable with PWM. For more information see the `DMC-60C Product Page `__ - -Venom Motor Controller -^^^^^^^^^^^^^^^^^^^^^^ - -.. image:: images/control-system-hardware/venom.jpg - :alt: Venom Motor Controller - :width: 500 - -The `Venom Motor Controller `__ from Playing With Fusion is integrated into a motor based on the original :term:`CIM`. Speed, current, temperature, and position are all measured onboard, enabling advanced control modes without complicated sensing and wiring schemes. - -Nidec Dynamo BLDC Motor with Controller -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. image:: images/control-system-hardware/nidec-dynamo.jpg - :alt: Nidec Dynamo BLDC Motor with Controller - :width: 500 - -The `Nidec Dynamo BLDC Motor with Controller `__ is the first brushless motor and controller legal in FRC. This motor's controller is integrated into the back of the motor. The `motor data sheet `__ provides more device specifics. - -SD540B and SD540C Motor Controllers -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. image:: images/control-system-hardware/sd540b-pwm.png - :alt: SD540B Motor Controller - :width: 500 - -The SD540B and SD540C Motor Controllers from Mindsensors are controlled using PWM. CAN control is no longer available for the SD540C due to lack of manufacturer support. Limit switches may be wired directly to the SD540 to limit motor travel in one or both directions. For more information see the `Mindsensors FRC page `__ - -Spike H-Bridge Relay --------------------- - -.. image:: images/control-system-hardware/spike-relay.png - :alt: Spike H-Bridge Relay - :width: 300 - -.. warning:: While this relay is still legal for FRC use, the manufacturer has discontinued this product. - -The Spike H-Bridge Relay from VEX Robotics is a device used for controlling power to motors or other custom robot electronics. When connected to a motor, the Spike provides On/Off control in both the forward and reverse directions. The Spike outputs are independently controlled so it can also be used to provide power to up to 2 custom electronic circuits. The Spike H-Bridge Relay should be connected to a relay output of the roboRIO and powered from the Power Distribution Panel. For more information, see the `Spike User’s Guide `__. - -Servo Power Module ------------------- - -.. image:: images/control-system-hardware/servo-power-module.png - :alt: Servo Power Module - :width: 300 - -The Servo Power Module from Rev Robotics is capable of expanding the power available to servos beyond what the roboRIO integrated power supply is capable of. The Servo Power Module provides up to 90W of 6V power across 6 channels. All control signals are passed through directly from the roboRIO. For more information, see the `Servo Power Module webpage `__. - -Microsoft Lifecam HD3000 ------------------------- - -.. image:: images/control-system-hardware/microsoft-lifecam.png - :alt: Microsoft Lifecam HD3000 - :width: 300 - -The Microsoft Lifecam HD3000 is a USB webcam that can be plugged directly into the roboRIO. The camera is capable of capturing up to 1280x720 video at 30 FPS. For more information about the camera, see the `Microsoft product page `__. For more information about using the camera with the roboRIO, see the :ref:`Vision Processing ` section of this documentation. - -Image Credits -------------- - -Image of roboRIO courtesy of National Instruments. Image of DMC-60 courtesy of Digilent. Image of SD540 courtesy of Mindsensors. Images of Jaguar Motor Controller, Talon SRX, Talon FX, Victor 888, Victor SP, Victor SPX, and Spike H-Bridge Relay courtesy of VEX Robotics, Inc. Image of SPARK MAX, Power Distribution Hub, Radio Power Module, and Pneumatic Hub courtesy of REV Robotics. Lifecam, PDP, PCM, SPARK, and VRM photos courtesy of *FIRST*\ |reg|. All other photos courtesy of AndyMark Inc. diff --git a/source/docs/controls-overviews/control-system-software.rd b/source/docs/controls-overviews/control-system-software.rd deleted file mode 100644 index 453c4c4d33..0000000000 --- a/source/docs/controls-overviews/control-system-software.rd +++ /dev/null @@ -1,160 +0,0 @@ -.. include:: - -Software Component Overview -=========================== - -The FRC\ |reg| software consists of a wide variety of mandatory and optional components. These elements are designed to assist you in the design, development, and debugging of your robot code as well as assist with control robot operation and to provide feedback when troubleshooting. For each software component this document will provide a brief overview of its purpose, a link to the package download, if appropriate, and a link to further documentation where available. - -Operating System Compatibility ------------------------------- - -The primary supported OS for FRC components is Windows. All required FRC software components have been tested on Windows 10 & 11. - -Many of the tools for C++/Java/Python programming are also supported and tested on macOS and Linux. Teams programming in C++/Java/Python should be able to develop using these systems, using a Windows system for the Windows-only operations such as the Driver Station, Radio Configuration Utility, and roboRIO Imaging Tool. - -LabVIEW FRC (Windows Only) --------------------------- - -.. image:: /docs/zero-to-robot/step-4/images/creating-test-program-labview/creating-a-project.png - :alt: LabVIEW FRC Getting Started screen. - -LabVIEW FRC, based on a recent version of LabVIEW Professional, is one of the three officially supported languages for programming an FRC robot. LabVIEW is a graphical, dataflow-driven language. LabVIEW programs consist of a collection of icons, called VIs, wired together with wires which pass data between the VIs. The LabVIEW FRC installer is distributed on a DVD found in the Kickoff Kit of Parts and is also available for download. A guide to getting started with the LabVIEW FRC software, including installation instructions can be found :ref:`here `. - -Visual Studio Code ------------------- - -.. image:: images/control-system-software/visual-studio-code.png - :alt: Welcome screen of Visual Studio Code. - -Visual Studio Code is the supported development environment for C++, Java. A guide to getting started with Java and C++ for FRC, including the installation and configuration of Visual Studio Code can be found :ref:`here `. - -FRC Driver Station Powered by NI LabVIEW (Windows Only) -------------------------------------------------------- - -.. image:: images/control-system-software/frc-driver-station.png - :alt: Driver Station on the first tab with the robot disabled and disconnected. - -This is the only software allowed to be used for the purpose of controlling the state of the robot during competition. This software sends data to your robot from a variety of input devices. It also contains a number of tools used to help troubleshoot robot issues. More information about the FRC Driver Station Powered by NI LabVIEW can be found :ref:`here `. - -Dashboard Options ------------------ - -LabVIEW Dashboard (Windows Only) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. image:: images/control-system-software/frc-labview-dashboard.png - :alt: The default LabVIEW Dashboard on the Drive tab. - -The LabVIEW Dashboard is automatically launched by the FRC Driver Station by default. The purpose of the Dashboard is to provide feedback about the operation of the robot using tabbed display with a variety of built in features. More information about the FRC Default Dashboard software can be found :ref:`here `. - -SmartDashboard -^^^^^^^^^^^^^^ - -.. image:: images/control-system-software/smartdashboard.png - :alt: SmartDashboard with 3 widgets added. - -SmartDashboard allows you to view your robot data by automatically creating customizable indicators specifically for each piece of data sent from your robot. Additional documentation on SmartDashboard can be found :ref:`here `. - -Shuffleboard -^^^^^^^^^^^^ - -.. image:: images/control-system-software/shuffleboard.png - :alt: Shuffleboard with 3 widgets from their NetworkTables entries added. - -Shuffleboard has the same features as SmartDashboard. It also improves on the setup and visualization of your data with new features and a modern design at the cost of being less resource efficient. Additional documentation on Shuffleboard can be found :ref:`here `. - -Glass -^^^^^ - -.. image:: images/control-system-software/glass.png - :alt: Glass connected and showing NetworkTables, a Field2D window, and a plot of a couple signals. - -:ref:`Glass ` is a Dashboard focused on being a programmer's tool for debugging. The primary advantages are the field view, pose visualization and advanced signal plotting tools. - -LiveWindow ----------- - -.. image:: images/control-system-software/livewindow-smartdashboard.png - :alt: LiveWindow showing two different subsystems. - -LiveWindow is a feature of SmartDashboard and Shuffleboard, designed for use with the Test Mode of the Driver Station. LiveWindow allows the user to see feedback from sensors on the robot and control actuators independent of the written user code. More information about LiveWindow can be found :ref:`here `. - -FRC roboRIO Imaging Tool (Windows Only) ---------------------------------------- - -.. image:: /docs/zero-to-robot/step-3/images/imaging-your-roborio/roborio-imaging-tool.png - :alt: roboRIO Imaging Tool after it has found a connected roboRIO. - -This tool is used to format and setup a roboRIO for use in FRC. Installation instructions can be found :ref:`here `. Additional instructions on imaging your roboRIO using this tool can be found :doc:`here `. - -FRC Radio Configuration Utility (Windows Only) ----------------------------------------------- - -.. image:: images/control-system-software/frc-radio-configuration-utility.png - :alt: Initial screen of the FRC Radio Configuration Utility. - -The FRC Radio Configuration Utility is a tool used to configure the standard radio for practice use at home. This tool sets the appropriate network settings to mimic the experience of the FRC playing field. The FRC Radio Configuration Utility is installed by a standalone installer that can be found :ref:`here `. - -FRC Driver Station Log Viewer (Windows Only) --------------------------------------------- - -.. image:: images/control-system-software/frc-log-viewer.png - :alt: Driver Station Log Viewer showing a logged practice session. - -The FRC Driver Station Log Viewer is used to view logs created by the FRC Driver Station. These logs contain a variety of information important for understanding what happened during a practice session or FRC match. More information about the FRC Driver Station Log Viewer and understanding the logs can be found :ref:`here ` - -RobotBuilder ------------- - -.. image:: images/control-system-software/robot-builder.png - :alt: RobotBuilder building a robot with two subsystems. - -RobotBuilder is a tool designed to aid in setup and structuring of a Command Based robot project for C++ or Java (Python not currently supported). RobotBuilder allows you to enter in the various components of your robot subsystems and operator interface and define what your commands are in a graphical tree structure. RobotBuilder will then generate structural template code to get you started. More information about RobotBuilder can be found :ref:`here `. More information about the Command Based programming architecture can be found :ref:`here `. - -Robot Simulation ----------------- - -.. image:: images/control-system-software/sim-gui.png - :alt: The Simulation GUI similar to Glass but also has Joysticks and control over the robot state and a few other features. - -Robot Simulation offers a way for Java, C++, and Python teams to verify their actual robot code is working in a simulated environment. This simulation can be launched directly from VS Code and includes a 2D field that users can visualize their robot's movement on. For more information see the :ref:`Robot Simulation section `. - -FRC LabVIEW Robot Simulator (Windows Only) ------------------------------------------- - -.. image:: images/control-system-software/robot-simulator.png - :alt: FRC LabVIEW Robot Simulator - -The FRC Robot Simulator is a component of the LabVIEW programming environment that allows you to operate a predefined robot in a simulated environment to test code and/or Driver Station functions. Information on using the FRC Robot Simulator can be found `here `__ or by opening the Robot Simulation Readme.html file in the LabVIEW Project Explorer. - -PathWeaver ----------- - -.. image:: images/control-system-software/pathweaver.png - :alt: PathWeaver UI with a project for FRC Deep Space plotting a trajectory to the back of the rocket. - -PathWeaver allows teams to quickly generate and configure paths for advanced autonomous routines. These paths have smooth curves allowing the team to quickly navigate their robot between points on the field. For more information see the :ref:`PathWeaver section `. - -System Identification ---------------------- - -.. image:: images/control-system-software/sysid.png - :alt: SysId UI showing diagnostics and analysis for a flywheel. - -This tool helps teams automatically calculate constants that can be used to describe the physical properties of your robot for use in features like robot simulation, trajectory following, and PID control. For more information see the :ref:`System Identification section `. - -OutlineViewer -------------- - -.. image:: images/control-system-software/outline-viewer.png - :alt: OutlineViewer with the preferences dialog box. - -OutlineViewer is a utility used to view, modify and add to all of the contents of the NetworkTables for debugging purposes. LabVIEW teams can use the Variables tab of the LabVIEW Dashboard to accomplish this functionality. For more information see the :ref:`Outline Viewer section `. - -roboRIO Team Number Setter --------------------------- - -.. image:: /docs/software/wpilib-tools/roborio-team-number-setter/images/roborioteamnumbersetter.png - :alt: roboRIO Team Number Setter tool. - -The roboRIO Team Number Setter is a cross-platform utility that can be used to set the team number on the roboRIO. It is an alternative to the roboRIO imaging tool for setting the team number. For more information see the :ref:`roboRIO Team Number Setter section `. diff --git a/source/docs/hardware/hardware-basics/can-wiring-basics.rd b/source/docs/hardware/hardware-basics/can-wiring-basics.rd deleted file mode 100644 index a8340e3d0d..0000000000 --- a/source/docs/hardware/hardware-basics/can-wiring-basics.rd +++ /dev/null @@ -1,24 +0,0 @@ -CAN Wiring Basics -================= - -:term:`CAN` is a two wire network that is designed to facilitate communication between multiple devices on your robot. It is recommended that CAN on your robot follow a "daisy-chain" topology. This means that the CAN wiring should usually start at your roboRIO and go into and out of each device successively until finally ending at the :term:`PDP`. - -.. image:: images/can-wiring-basics/daisychain.png - -Standard Wiring ---------------- - -CAN is generally wired with yellow and green wire with yellow acting as the CAN-High and green as the CAN-Low signals. Many devices show this yellow and green color scheme to indicate how the wires should be plugged in. - -CAN wiring from the roboRIO to the PCM. - -.. image:: /docs/zero-to-robot/step-1/images/how-to-wire-a-simple-robot/pcm-can.jpg - -CAN wiring from the PCM to the PDP. - -.. image:: /docs/zero-to-robot/step-1/images/how-to-wire-a-simple-robot/pdp-can.jpg - -Termination ------------ - -It is recommended that the wiring starts at the roboRIO and ends at the PDP because the CAN network is required to be terminated by 120 :math:`\Omega` resistors and these are built into these two devices. The PDP ships with the CAN bus terminating resistor jumper in the "ON" position. It is recommended to leave the jumper in this position and place any additional CAN nodes between the roboRIO and the PDP (leaving the PDP as the end of the bus). If you wish to place the PDP in the middle of the bus (utilizing both pairs of PDP CAN terminals) move the jumper to the "OFF" position and place your own 120 :math:`\Omega` terminating resistor at the end of your CAN bus chain. diff --git a/source/docs/hardware/hardware-basics/index.rd b/source/docs/hardware/hardware-basics/index.rd deleted file mode 100644 index 3418223b49..0000000000 --- a/source/docs/hardware/hardware-basics/index.rd +++ /dev/null @@ -1,14 +0,0 @@ -Hardware - Basics -================= - -.. toctree:: - :maxdepth: 1 - - /docs/controls-overviews/control-system-hardware - wiring-best-practices - can-wiring-basics - wiring-pneumatics-pcm - wiring-pneumatics-ph - status-lights-ref - preemptive-troubleshooting - robot-battery diff --git a/source/docs/hardware/hardware-basics/preemptive-troubleshooting.rd b/source/docs/hardware/hardware-basics/preemptive-troubleshooting.rd deleted file mode 100644 index 6e6bf1976c..0000000000 --- a/source/docs/hardware/hardware-basics/preemptive-troubleshooting.rd +++ /dev/null @@ -1,161 +0,0 @@ -.. include:: - -Robot Preemptive Troubleshooting -================================ - -.. note:: - - In *FIRST*\ |reg| Robotics Competition, robots take a lot of stress while driving around the field. It is important to make sure that connections are tight, parts are bolted securely in place and that everything is mounted so that a robot bouncing around the field does not break. - -Check Battery Connections -------------------------- - -.. image:: images/preemptive-troubleshooting/preCheckBatt.png - :alt: Trying to wiggle the battery terminal by hand. - :width: 500 - -The tape that should be covering the battery connection in these examples has been removed to illustrate what is going on. On your robots, the connections should be covered. - -Wiggle battery harness connector. Often these are loose because the screws loosen, or sometimes the crimp is not completely closed. You will only catch the really bad ones though because often the electrical tape stiffens the connection to a point where it feels stiff. Using a voltmeter or Battery Beak will help with this. - -Apply considerable force onto the battery cable at 90 degrees to try to move the direction of the cable leaving the battery, if successful the connection was not tight enough to begin with and it should be redone. This :ref:`article ` has more detailed battery information. - -Securing the Battery to the Robot ---------------------------------- - -.. image:: images/preemptive-troubleshooting/preCheckConnecc.png - :alt: Disconnected battery of a robot mid match. - :width: 350 - -In almost every event we see at least one robot where a not properly secured battery connector (the large Anderson) comes apart and disconnects power from the robot. This has happened in championship matches on the Einstein and everywhere else. Its an easy to ensure that this doesn't happen to you by securing the two connectors by wrapping a tie wrap around the connection. 10 or 12 tie wraps for the peace of mind during an event is not a high price to pay to guarantee that you will not have the problem of this robot from an actual event after a bumpy ride over a defense. Also, secure your battery to the chassis with hook and loop tape or another method, especially in games with rough defense, obstacles or climbing. - -Securing the Battery Connector & Main Power Leads -------------------------------------------------- - -A loose robot-side battery connector (the large Anderson SB) can allow the main power leads to be tugged when the battery is replaced. If the main power leads are loose, that "tug" can get all the way back to the crimp lugs attached to the 120 Amp Circuit Breaker or Power Distribution Panel (PDP), bend the lug, and over time cause the lug end to break from fatigue. Putting a couple tie wraps attaching the main power leads to the chassis and bolting down the robot-side battery connector can prevent this, as well as make it easier to connect the battery. - -Main Breaker (120 Amp Circuit Breaker) --------------------------------------- - -.. note:: Ensure nuts are tightened firmly and the breaker is attached to a rigid element. - -.. image:: images/preemptive-troubleshooting/preCheckBreaker-1.png - :alt: Applying a twisting force to the first cable on the breaker. - :width: 350 - -.. image:: images/preemptive-troubleshooting/preCheckBreaker-2.png - :alt: Applying a twisting force to the second cable on the breaker. - :width: 350 - -Apply a strong twisting force to try to rotate the crimped lug. If the lug rotates then the nut is not tight enough. After tightening the nut, retest by once again trying to rotate the lug. - -The original nut has a star locking feature, which can wear out over time: these may require checking every few matches, especially if your robot-side battery connector is not attached to the chassis. - -The nut is normally a relatively uncommon 1/4-28 thread: ensure this is correct if the nut is replaced. - -Because the metal stud is just molded into the case, every once in awhile you may break off the stud. Don't stress, just replace the assembly. - -When subjected to multiple competition seasons, the Main Breaker is susceptible to fatigue damage from vibration and use, and can start opening under impact. Each time the thermal fuse function is triggered, it can become progressively easier to trip. Many veteran teams start each season with a fresh main breaker, and carry spares. - -Power Distribution Panel (PDP) ------------------------------- - -.. image:: images/preemptive-troubleshooting/pdp-bolts.png - :alt: Battery terminals on the PDP. - :width: 500 - -Make sure that split washers were placed under the PDP screws, but it is not easy to visually confirm, and sometimes you can’t. You can check by removing the case. -Also if you squeeze the red and black wires together, sometimes you can catch the really lose connections. - -Tug Testing ------------ - -.. image:: images/preemptive-troubleshooting/preCheckTug-1.png - :alt: Tug test on the roboRIO power. - :width: 350 - -.. image:: images/preemptive-troubleshooting/preCheckTug-2.png - :alt: Tug test on the connectors at the bottom of the PDP. - :width: 350 - -The Weidmuller contacts for power, compressor output, roboRIO power connector, and radio power are important to verify by tugging on the connections as shown. Make sure that none of the connections pull out. - -Look for possible or impending shorts with Weidmuller connections that are close to each other, and have too-long wire-lead lengths (wires that are stripped extra long). - -Spade connectors can also fail due to improper crimps, so tug-test those as well. - -Blade Fuses ------------ - -Be sure to place the 20A fuse (yellow) on the left and the 10A fuse (red) on the right. - -.. image:: images/preemptive-troubleshooting/pdp-blade-fuses.svg - :alt: PDP diagram showing the bottom connections and fuses. - :width: 600 - -.. image:: images/preemptive-troubleshooting/blade-fuses.png - :alt: Bottom of the PDP focusing on the 20A and 10A fuses. - :width: 600 - -.. warning:: Take care to ensure fuses are fully seated into the fuse holders. The fuses should descend at least as far as the figure below (different brand fuses have different lead lengths). It should be nearly impossible to remove the fuse with bare hands (without the use of pliers). If this is not properly done, the robot/radio may exhibit intermittent connectivity issues. - -If you can remove the blade fuses by hand then they are not in completely. Make sure that they are completely seated in the PDP so that they don't pop out during robot operation. - -roboRIO swarf -------------- - -Swarf is fine chips or filings of stone, metal, or other material produced by a machining operation. Often modifications must be made to a robot while the control system parts are in place. The circuit board for the roboRIO is conformally coated, but that doesn't absolutely guarantee that metal chips won't short out traces or components inside the case. In this case, you must exercise care in making sure that none of the chips end up in the roboRIO or any of the other components. In particular, the exposed 3 pin headers are a place where chips can enter the case. A quick sweep through each of the four sides with a flashlight is usually sufficient to find the really bad areas of infiltration. - -Radio Barrel Jack ------------------ - -Make sure the correct barrel jack is used, not one that is too small and falls out for no reason. This isn’t common, but ask an :term:`FTA` and every once in awhile a team will use some random barrel jack that is not sized correctly, and it falls out in a match on first contact. - -Ethernet Cable --------------- - -If the RIO to radio ethernet cable is missing the clip that locks the connector in, get another cable. This is a common problem that will happen several times in every competition. Make sure that your cables are secure. The clip often breaks off, especially when pulling it through a tight path, it snags on something then breaks. - -Loose Cables ------------- - -Cables must be tightened down, particularly the radio power and ethernet cable. The radio power cables don’t have a lot of friction force and will fall out (even if it is the correct barrel) if the weight of the cable-slack is allowed to swing freely. - -Ethernet cable is also pretty heavy, if it’s allowed to swing freely, the plastic clip may not be enough to hold the ethernet pin connectors in circuit. - -Reproducing Problems in the Pit -------------------------------- - -Beyond the normal shaking of cables whilst the robot is powered and tethered, it is suggested that one side of the robot be picked up and dropped. Driving on the field, especially against defenders, will often be very violent, and this helps makes sure nothing falls out. It is better for the robot to fail in the pits rather than in the middle of a match. - -When doing this test it’s important to be ethernet tethered and not USB tethered, otherwise you are not testing all of the critical paths. - -Check Firmware and Versions ---------------------------- - -Robot inspectors do this, but you should do it as well, it helps robot inspectors out and they appreciate it. And it guarantees that you are running with the most recent, bug fixed code. You wouldn't want to lose a match because of an out of date piece of control system software on your robot. - -Driver Station Checks ---------------------- - -We often see problems with the Drivers Station. You should: - -- ALWAYS bring the laptop power cable to the field, it doesn’t matter how good the battery is, you are allowed to plug in at the field. -- Check the power and sleep settings, turn off sleep and hibernate, screen savers, etc. -- Turn off power management for USB devices (dev manager) -- Turn off power management for ethernet ports (dev manager) -- Turn off windows defender -- Turn off firewall -- Close all apps except for DS/Dashboard when out on the field. -- Verify that there is nothing unnecessary running in the application tray in the start menu (bottom right side) - -Handy Tools ------------ - -.. image:: images/preemptive-troubleshooting/tools.png - :alt: A Wago screwdriver and flashlight. - :width: 500 - -There never seems to be enough light inside robots, at least not enough to scrutinize the critical connection points, so consider using a handheld LED flashlight to inspect the connections on your robot. They're available from home depot or any hardware/automotive store. - -A WAGO tool is nice tool for redoing Weidmuller connections with stranded wires. Often I’ll do one to show the team, and then have them do the rest using the WAGO tool to press down the white-plunger while they insert the stranded wire. The angle of the WAGO tool makes this particularly helpful. diff --git a/source/docs/hardware/hardware-basics/robot-battery.rd b/source/docs/hardware/hardware-basics/robot-battery.rd deleted file mode 100644 index 30152315f8..0000000000 --- a/source/docs/hardware/hardware-basics/robot-battery.rd +++ /dev/null @@ -1,200 +0,0 @@ -.. include:: - -Robot Battery Basics -==================== - -The power supply for an FRC\ |reg| robot is a single 12V 18Ah SLA (Sealed Lead Acid) non-spillable battery, capable of briefly supplying over 180A and arcing over 500A when fully charged. The Robot Battery assembly includes the :term:`COTS` battery, lead cables with contacts, and Anderson SB connector. Teams are encouraged to have multiple Robot Batteries. - -COTS Battery ------------- - -The Robot Rules in the Game Manual specify a COTS non-spillable sealed lead acid battery meeting specific criteria, and gives examples of legal part numbers from a variety of vendors. - -Battery Safety & Handling -------------------------- - -A healthy battery is **always** "On" and the terminals are **always** energized. If the polarities short together - for example, a wrench or aerosol can falls and bridges the gap between two bare terminals - all the stored energy will be released in a dangerous arc. This risk drives a wide range of best practices, such as covering terminals in storage, only uncovering and working on one terminal or polarity at a time, keeping SB contacts fully inserted in connectors, etc. - -**Do *NOT* carry a battery assembly by the cables**, and always avoid pulling by them. Pulling on batteries by the cables will begin to damage the lugs, tabs, and the internal connection of the tab. Over time, fatigue damage can add up until the entire tab tears out of the housing! Even if it isn't clearly broken, internal fatigue damage can increase the battery internal resistance, prematurely wearing out the battery. The battery will not be able to provide the same amount of current with increased internal resistance or if the :ref:`connectors are loose `. - -.. image:: images/robot-battery/broken-terminal.png - :alt: One terminal of an FRC battery fully detached from the battery. - -Dropping the batteries can bend the internal plates and cause performance issues, create bulges, or even crack the battery case open. While most FRC batteries use Absorbent Glass Mat [AGM] or Gel technology for safety and performance, when a cell is punctured it may still leak a small amount of battery acid. This is one of the reasons FIRST recommends teams have a battery spill kit available. - -Finally, certain older battery chargers without "maintenance mode" features can *overcharge* the battery, resulting in boiling off some of the battery acid. - -.. image:: images/robot-battery/boiled.jpg - :alt: An FRC battery that was boiled by a high current dumb charger. - -Damaged batteries should be safely disposed of as soon as possible. All retailers that sell large SLA batteries, like car batteries, should be able to dispose of it for you. They may charge a small fee, or provide a small "core charge refund", depending on your state law. - -.. danger:: **DO NOT** attempt to "repair" damaged or non-functional batteries. - -Battery Construction & Tools ----------------------------- - -Battery Leads -^^^^^^^^^^^^^ - -Battery leads must be copper, minimum size (cross section) 6 AWG (16mm2, 7 SWG) and maximum length 12", color coded for polarity, with an Anderson SB connector. Standard 6AWG copper leads with Pink/Red SB50 battery leads often come in the Kit of Parts and are sold by FRC vendors. - -Lead Cables -~~~~~~~~~~~ - -Tinned, annealed, or coated copper is allowed. Do not use CCA (copper clad aluminum), aluminum, or other non-copper base metal. The conductor metal is normally printed on the outside of the insulation with the other cable ratings. - -Wire size 6AWG is sufficient for almost all robots and fits standard SB50 contacts. A small number of teams adopt larger wire sizes for marginal performance benefits. - -Higher strand count wire (sometimes sold as "Flex" or "welding wire") has a smaller bend radius, which makes it easier to route, and a higher fatigue limit. There is no strand count requirement, but 84/25 (84 strand "flex" hookup wire) and 259/30 (259 strand "welding wire") will both be *much* easier to work with than 19/0.0372 (19 strand hookup wire). - -The insulation must be color-coded per the Game Manual: the +12Vdc wire must be red, white, brown, yellow, or black w/stripe and the ground wire (return wire) must be black or blue. There is no explicit insulation temperature rating requirement, but any blackened or damaged insulation means the wire needs to be replaced: off hand, 105C is plenty and lower will work for almost all robots. There is no insulation voltage rating requirement, lower is better for thinner insulation. - -SB Connector -~~~~~~~~~~~~ - -The Anderson SB Connector may be the standard Pink/Red SB50, or another Anderson SB connector. Teams are *STRONGLY* recommended to use the Pink/Red SB50 for interoperability: the other colors and sizes of housings will not intermate, and you will be unable to borrow batteries or chargers. - -Follow manufacturer's instructions to crimp contacts and assemble the leads into Anderson SB connectors. A small flathead screwdriver can help to insert the contacts (push on the contact, not on the wire insulation), or it can help to disengage the internal latch if the contact is in the wrong slot or upside down. - -Battery Lugs -^^^^^^^^^^^^ - -Compression lugs ("crimp lugs") for #10 bolt (or M5) battery tabs (~0.2" or ~5mm hole diameter) are available online and through electrical supply houses, sold by the accepted wire sizes in AWG (or mm2) and post diameter ("bolt size", "hole diameter"). Higher end vendors will also distinguish between Standard (~19) and Flex (>80) strand counts in their lug catalogs. Some vendors also offer right angle lugs, in addition to more common straight styles. Follow manufacturer's instructions to crimp the lugs. - -Screw terminal lugs are legal, but not recommended. If using screw terminal lugs, use the correct tip size screwdriver to tighten the terminal. Check the terminal tightness frequently because they may loosen over time. - -Battery Lead Lug To Post Connection -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -A #10 or M5 nut & bolt connect the battery lead lug to the battery tab. - -.. warning:: The lug and tab must directly contact, copper to copper: do not put a washer of any kind separating them. - -.. image:: images/robot-battery/tab-contact.jpg - :alt: One terminal of an FRC battery with socket head bolt and nylon locking (nylock) nut. - -Some batteries come with tab bolts in the package: they may be used, or replaced with stronger alloy steel bolts. It is a good idea to add a functional lock washer, such as a #10 star washer or a nordlock washer system, in addition to a nylon locking ("nylock") nut. Only use one style of lock washer in each connection. Even if the manufacturer provides split ring lock washers in the package, you are not required to use them. - -.. image:: images/robot-battery/loose-nordlock.jpg - :alt: One terminal of an FRC battery with socket head bolt, nordlock locking nuts, and nylon locking (nylock) nut. - -These connections must be very tight for reliability. Any movement of the lug while in operation may interrupt robot power, resulting in robot reboots and field disconnections lasting 30 seconds or more. - -This connection must also be completely covered for electrical safety; electrical tape will work, but heatshrink that fits over the entire connection is recommended. High shrink ratios (minimum 3:1, recommend 4:1) will make it easier to apply the heatshrink. Adhesive lined heat shrink is allowed. Be sure *all* the copper is covered! Heat shrink must be "touched up" with electrical tape if some copper shows. - -.. image:: images/robot-battery/heatshrink.png - :alt: One terminal of an FRC battery fully covered in heatshrink. - -Battery Chargers -^^^^^^^^^^^^^^^^ - -There are many good COTS "smart" battery chargers designed for 12V SLA batteries, rated for 6A or less per battery, with 'maintenance mode' features. Chargers rated over 6A are not allowed in FRC pits. - -Chargers used at competition are required to use Anderson SB connectors. Attaching a COTS SB connector battery lead to the charger leads using appropriately sized wire nuts or screw terminals is fast and simple (be sure to cover any exposed copper with heat shrink or electrical tape). SB Connector Contacts are also available for smaller wire sizes, if the team has crimping capability. - -.. warning:: After attaching the SB, double check the charger polarities with a multimeter before plugging in the first battery. - -Some FRC vendors sell chargers with red SB50 connectors pre-attached. - -Battery Evaluation Tools -^^^^^^^^^^^^^^^^^^^^^^^^ - -**Battery Charger** - -If your battery charger has Maintenance Mode indicator, such as a GREEN LED, you can use that indicator to tell you whether you are READY. Some chargers will cycle between "CHARGING" and "READY" periodically. This is a "maintenance" behavior, sometimes associated with the battery cooling off and being able to accept more charge. - -**Driver Station Display and Log** - -When the robot is plugged in and connected to the driver station laptop, the battery voltage is displayed on the NI Driver Station software. - -After you finish a driving session, you can :ref:`review the battery voltage in the Log Viewer. ` - -Hand-held **Voltmeter** or **Multimeter** - -A voltage reading from probes on the SB connector of a disconnected battery will give you a snapshot of what the Voc (Voltage open circuit, or "float voltage") is in the "Unloaded" state. In general the Voc is not a recommended method for understanding battery health: the open circuit voltage is not as useful as the combination of internal resistance and voltages at specific loads provided by a Load Tester (or Battery Analyzer). - -**Load Tester** - -A battery load tester can be used as a quick way to determine the detailed readiness of a battery. It may provide information like: open-load voltage, voltage under load, internal resistance, and state of charge. These metrics can be used to quickly confirm that a battery is ready for a match and even help to identify some long term problems with the battery. - -.. image:: images/robot-battery/beak.png - :alt: Output screen of a common load tester showing properties of the battery. - -Ideal internal resistance should be less than 0.015 Ohms. The manufacturer specification for most batteries is 0.011 Ohms. If a battery gets higher than 0.020 Ohms it is a good idea to consider not using that battery for competition matches. - -If a battery shows significantly lower voltages at the higher test current loads, it may not be done charging, or it may need to be retired. - -Understanding Battery Voltages ------------------------------- - -A "12V battery" is anything but 12.0V. - -Fully charged, a battery can be anywhere from 12.7 to 13.5 volts open circuit (Voc). Open circuit voltage is measured with *nothing* connected. - -Once a load (like a robot) is connected, and any amount of current is flowing, the battery voltage will drop. So if you check a battery with a Voltmeter, and it reads 13.2, and then connect it to your robot and power on, it will read lower, maybe 12.9 on the Driver Station display. Those numbers will vary with every battery and specific robot, see Characterization below. Once your robot starts running, it will pull more current, and the voltage will drop further. - -Batteries reading 12.5V on an idle robot should be swapped and charged before a match. Always swap the batteries before the robot starts reaching brownout safety thresholds (dwelling at low voltages on the Driver Station display), as frequently entering low voltage ranges risks permanent battery damage; this behavior can happen at a variety of Voc states depending on battery health, battery manufacturer, and robot design. The battery State of Charge should be kept over 50% for battery longevity. - -Battery voltage and current also depends on temperature: cool batteries are happy batteries. - -Battery Characterization -^^^^^^^^^^^^^^^^^^^^^^^^ - -A battery analyzer can be used to give a detailed inspection and comparison of battery performance. - -.. image:: images/robot-battery/cba-graph.jpg - :alt: Graph from a common battery analyzer plotting volts and AmpHrs for many different batteries. - -It will provide graphs of battery performance over time. This test takes significant time (roughly two hours) so it is less suited to testing during competition. It is recommended to run this test on each battery every year to monitor and track its performance. This will determine how it should be used: matches, practice, testing, or disposed of. - -At the standard 7.5 amps test load, competition batteries should have at least a 11.5 amp hour rating. Anything less than that should only be used for practice or other less demanding use cases. - -Battery Longevity -^^^^^^^^^^^^^^^^^ - -A battery is rated for about 1200 normal charge/recharge cycles. The high currents required for an FRC match reduce that lifespan to about 400 cycles. These cycles are intended to be relatively low discharge, from around 13.5 down to 12 or 12.5 volts. Deep cycling the battery (running it all the way down) will damage it. - -Batteries last the longest if they are kept fully charged when not in use, either by charging regularly or by use of a maintenance charger. Batteries drop roughly 0.1V every month of non-use. - -Batteries need to be kept away from both extreme heat and cold. This generally means storing the batteries in a climate controlled area: a classroom closet is usually fine, a parking lot shipping container is more risky. - -Battery Best Practices ----------------------- - -- Only use a charged battery for competition matches. If you are in a situation where you have run out of charged batteries, please ask a veteran team for help! Nobody wants to see a robot dead on the field (:ref:`brownout `) due to a bad or uncharged battery. - -- Teams are strongly recommended to use properly rated tools and stringent quality control practices for crimping processes (ask local veteran teams or a commercial electrician for help), or use vendor-made Battery Leads. - -- Wait for batteries to cool after the match before recharging: the case should not be warm to the touch, fifteen minutes is usually plenty. - -- Teams should consider purchasing several new batteries each year to help keep their batteries fresh. Elimination matches can require many batteries and there may not be enough time to recharge. - -.. image:: images/robot-battery/battery-cart.jpg - :alt: A wooden bookcase like cart for storing and charging batteries. - -- A multi bank battery charger allows you to charge more than one battery at a time. Many teams build a robot cart for their batteries and chargers allowing for easy transport and storage. - -- It is a good idea to permanently identify each battery with at least: team number, year, and a unique identifier. - -- Teams may also want to use something removable (stickers, labeling machine etc.) to identify what that battery should be used for based on its performance data and when the last analyzer test was run. - -.. image:: images/robot-battery/battery-flag.jpg - :alt: A battery flag is just a small piece of plastic that fits in the battery connector. - -- Using battery flags (a piece of plastic placed in the battery connector) is a common way to indicate that a battery has been charged. Battery flags can also be easily 3D printed. - -- Handles for SB50 contacts can be purchased or 3D printed to help avoid pulling on the leads while connecting or disconnecting batteries. Do not use these handles to carry the weight of the battery. - -.. image:: images/robot-battery/sb50-handle.png - :alt: A plastic handle bolted on to an assembled SB50 connector. - -- Some teams sew battery carrying straps from old seatbelts or other flat nylon that fit around the battery to help prevent carrying by leads. - -.. image:: images/robot-battery/battery-strap.png - :alt: An example showing a 2" wide nylon strap, wrapped around the battery and sewn into a loop. - -- Cable tie edge clips can be used with 90 degree crimp lugs to strain relieve battery leads. - -.. image:: images/robot-battery/edge-clip.png - :alt: An example showing edge clips with zipties holding leads on a battery. diff --git a/source/docs/hardware/hardware-basics/status-lights-ref.rd b/source/docs/hardware/hardware-basics/status-lights-ref.rd deleted file mode 100644 index e69de29bb2..0000000000 From b9d764b22db7b8f717478ac4da9910c06246e352 Mon Sep 17 00:00:00 2001 From: Falon <47285315+falOn-Dev@users.noreply.github.com> Date: Sat, 7 Sep 2024 12:49:17 -0400 Subject: [PATCH 17/19] Update check_codeblock_coverage.py --- scripts/check_codeblock_coverage.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/scripts/check_codeblock_coverage.py b/scripts/check_codeblock_coverage.py index beb7ab17a0..b7554a26da 100644 --- a/scripts/check_codeblock_coverage.py +++ b/scripts/check_codeblock_coverage.py @@ -190,8 +190,6 @@ def main(): # Parse the command line arguments args = parser.parse_args() - print(generate_language_regex(args.langs)) - # Get all .rst files from the specified directory files = get_all_rst_files(dir=args.dir) blocks = [] From d373466c967ef35b4e38b02176657179eb805088 Mon Sep 17 00:00:00 2001 From: Falon <47285315+falOn-Dev@users.noreply.github.com> Date: Sun, 8 Sep 2024 20:19:51 -0400 Subject: [PATCH 18/19] Add --help to explain usage --- scripts/check_codeblock_coverage.py | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/scripts/check_codeblock_coverage.py b/scripts/check_codeblock_coverage.py index b7554a26da..91f36fabc9 100644 --- a/scripts/check_codeblock_coverage.py +++ b/scripts/check_codeblock_coverage.py @@ -166,7 +166,8 @@ def main(): """ # Set up argument parsing parser = argparse.ArgumentParser( - description="Check code block coverage in FRC docs" + description="Check code block coverage in FRC docs", + add_help=False, ) parser.add_argument("--dir", type=str, help="Directory to search for rst files") parser.add_argument( @@ -186,10 +187,19 @@ def main(): default=["java", "python", "c++"], help="Languages to check for", ) + parser.add_argument( + "--help", + action="store_true", + help="Displays the help message", + ) # Parse the command line arguments args = parser.parse_args() + if args.help: + print(__doc__) + return + # Get all .rst files from the specified directory files = get_all_rst_files(dir=args.dir) blocks = [] From 9e8136725df8ff7604973d8db175dc7f4310e60a Mon Sep 17 00:00:00 2001 From: Falon <47285315+falOn-Dev@users.noreply.github.com> Date: Mon, 9 Sep 2024 18:29:25 -0400 Subject: [PATCH 19/19] Update check_codeblock_coverage.py --- scripts/check_codeblock_coverage.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/scripts/check_codeblock_coverage.py b/scripts/check_codeblock_coverage.py index 91f36fabc9..e88ca1ac3c 100644 --- a/scripts/check_codeblock_coverage.py +++ b/scripts/check_codeblock_coverage.py @@ -148,6 +148,7 @@ def generate_report( # If verbose flag is set, print detailed information about missing code blocks if verbose: + print("Outputting missing code blocks to:", output) print("\n\nMissing code blocks:", file=stream) for block in blocks: missing_langs = [lang for lang in langs if lang not in block.langs] @@ -196,6 +197,10 @@ def main(): # Parse the command line arguments args = parser.parse_args() + if not len(sys.argv) > 1: + print(__doc__) + return + if args.help: print(__doc__) return