Initial Check-in of CLI Library (47b5f8d1) | Commits | arduino / CLI

Browse Code »

Commit 47b5f8d1ea55c2ac10b6e4a1d26a7ab1afd7d18b

Authored by Frederik Lindenaar 6 years ago

0 parents

master

Initial Check-in of CLI Library

Inline Side-by-side

Showing 15 changed files with 2477 additions and 0 deletions

LICENSE.txt 0 → 100644

View file @47b5f8d

		1	+++ a/LICENSE.txt
		1	+ GNU GENERAL PUBLIC LICENSE
		2	+ Version 3, 29 June 2007
		3	+
		4	+ Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
		5	+ Everyone is permitted to copy and distribute verbatim copies
		6	+ of this license document, but changing it is not allowed.
		7	+
		8	+ Preamble
		9	+
		10	+ The GNU General Public License is a free, copyleft license for
		11	+software and other kinds of works.
		12	+
		13	+ The licenses for most software and other practical works are designed
		14	+to take away your freedom to share and change the works. By contrast,
		15	+the GNU General Public License is intended to guarantee your freedom to
		16	+share and change all versions of a program--to make sure it remains free
		17	+software for all its users. We, the Free Software Foundation, use the
		18	+GNU General Public License for most of our software; it applies also to
		19	+any other work released this way by its authors. You can apply it to
		20	+your programs, too.
		21	+
		22	+ When we speak of free software, we are referring to freedom, not
		23	+price. Our General Public Licenses are designed to make sure that you
		24	+have the freedom to distribute copies of free software (and charge for
		25	+them if you wish), that you receive source code or can get it if you
		26	+want it, that you can change the software or use pieces of it in new
		27	+free programs, and that you know you can do these things.
		28	+
		29	+ To protect your rights, we need to prevent others from denying you
		30	+these rights or asking you to surrender the rights. Therefore, you have
		31	+certain responsibilities if you distribute copies of the software, or if
		32	+you modify it: responsibilities to respect the freedom of others.
		33	+
		34	+ For example, if you distribute copies of such a program, whether
		35	+gratis or for a fee, you must pass on to the recipients the same
		36	+freedoms that you received. You must make sure that they, too, receive
		37	+or can get the source code. And you must show them these terms so they
		38	+know their rights.
		39	+
		40	+ Developers that use the GNU GPL protect your rights with two steps:
		41	+(1) assert copyright on the software, and (2) offer you this License
		42	+giving you legal permission to copy, distribute and/or modify it.
		43	+
		44	+ For the developers' and authors' protection, the GPL clearly explains
		45	+that there is no warranty for this free software. For both users' and
		46	+authors' sake, the GPL requires that modified versions be marked as
		47	+changed, so that their problems will not be attributed erroneously to
		48	+authors of previous versions.
		49	+
		50	+ Some devices are designed to deny users access to install or run
		51	+modified versions of the software inside them, although the manufacturer
		52	+can do so. This is fundamentally incompatible with the aim of
		53	+protecting users' freedom to change the software. The systematic
		54	+pattern of such abuse occurs in the area of products for individuals to
		55	+use, which is precisely where it is most unacceptable. Therefore, we
		56	+have designed this version of the GPL to prohibit the practice for those
		57	+products. If such problems arise substantially in other domains, we
		58	+stand ready to extend this provision to those domains in future versions
		59	+of the GPL, as needed to protect the freedom of users.
		60	+
		61	+ Finally, every program is threatened constantly by software patents.
		62	+States should not allow patents to restrict development and use of
		63	+software on general-purpose computers, but in those that do, we wish to
		64	+avoid the special danger that patents applied to a free program could
		65	+make it effectively proprietary. To prevent this, the GPL assures that
		66	+patents cannot be used to render the program non-free.
		67	+
		68	+ The precise terms and conditions for copying, distribution and
		69	+modification follow.
		70	+
		71	+ TERMS AND CONDITIONS
		72	+
		73	+ 0. Definitions.
		74	+
		75	+ "This License" refers to version 3 of the GNU General Public License.
		76	+
		77	+ "Copyright" also means copyright-like laws that apply to other kinds of
		78	+works, such as semiconductor masks.
		79	+
		80	+ "The Program" refers to any copyrightable work licensed under this
		81	+License. Each licensee is addressed as "you". "Licensees" and
		82	+"recipients" may be individuals or organizations.
		83	+
		84	+ To "modify" a work means to copy from or adapt all or part of the work
		85	+in a fashion requiring copyright permission, other than the making of an
		86	+exact copy. The resulting work is called a "modified version" of the
		87	+earlier work or a work "based on" the earlier work.
		88	+
		89	+ A "covered work" means either the unmodified Program or a work based
		90	+on the Program.
		91	+
		92	+ To "propagate" a work means to do anything with it that, without
		93	+permission, would make you directly or secondarily liable for
		94	+infringement under applicable copyright law, except executing it on a
		95	+computer or modifying a private copy. Propagation includes copying,
		96	+distribution (with or without modification), making available to the
		97	+public, and in some countries other activities as well.
		98	+
		99	+ To "convey" a work means any kind of propagation that enables other
		100	+parties to make or receive copies. Mere interaction with a user through
		101	+a computer network, with no transfer of a copy, is not conveying.
		102	+
		103	+ An interactive user interface displays "Appropriate Legal Notices"
		104	+to the extent that it includes a convenient and prominently visible
		105	+feature that (1) displays an appropriate copyright notice, and (2)
		106	+tells the user that there is no warranty for the work (except to the
		107	+extent that warranties are provided), that licensees may convey the
		108	+work under this License, and how to view a copy of this License. If
		109	+the interface presents a list of user commands or options, such as a
		110	+menu, a prominent item in the list meets this criterion.
		111	+
		112	+ 1. Source Code.
		113	+
		114	+ The "source code" for a work means the preferred form of the work
		115	+for making modifications to it. "Object code" means any non-source
		116	+form of a work.
		117	+
		118	+ A "Standard Interface" means an interface that either is an official
		119	+standard defined by a recognized standards body, or, in the case of
		120	+interfaces specified for a particular programming language, one that
		121	+is widely used among developers working in that language.
		122	+
		123	+ The "System Libraries" of an executable work include anything, other
		124	+than the work as a whole, that (a) is included in the normal form of
		125	+packaging a Major Component, but which is not part of that Major
		126	+Component, and (b) serves only to enable use of the work with that
		127	+Major Component, or to implement a Standard Interface for which an
		128	+implementation is available to the public in source code form. A
		129	+"Major Component", in this context, means a major essential component
		130	+(kernel, window system, and so on) of the specific operating system
		131	+(if any) on which the executable work runs, or a compiler used to
		132	+produce the work, or an object code interpreter used to run it.
		133	+
		134	+ The "Corresponding Source" for a work in object code form means all
		135	+the source code needed to generate, install, and (for an executable
		136	+work) run the object code and to modify the work, including scripts to
		137	+control those activities. However, it does not include the work's
		138	+System Libraries, or general-purpose tools or generally available free
		139	+programs which are used unmodified in performing those activities but
		140	+which are not part of the work. For example, Corresponding Source
		141	+includes interface definition files associated with source files for
		142	+the work, and the source code for shared libraries and dynamically
		143	+linked subprograms that the work is specifically designed to require,
		144	+such as by intimate data communication or control flow between those
		145	+subprograms and other parts of the work.
		146	+
		147	+ The Corresponding Source need not include anything that users
		148	+can regenerate automatically from other parts of the Corresponding
		149	+Source.
		150	+
		151	+ The Corresponding Source for a work in source code form is that
		152	+same work.
		153	+
		154	+ 2. Basic Permissions.
		155	+
		156	+ All rights granted under this License are granted for the term of
		157	+copyright on the Program, and are irrevocable provided the stated
		158	+conditions are met. This License explicitly affirms your unlimited
		159	+permission to run the unmodified Program. The output from running a
		160	+covered work is covered by this License only if the output, given its
		161	+content, constitutes a covered work. This License acknowledges your
		162	+rights of fair use or other equivalent, as provided by copyright law.
		163	+
		164	+ You may make, run and propagate covered works that you do not
		165	+convey, without conditions so long as your license otherwise remains
		166	+in force. You may convey covered works to others for the sole purpose
		167	+of having them make modifications exclusively for you, or provide you
		168	+with facilities for running those works, provided that you comply with
		169	+the terms of this License in conveying all material for which you do
		170	+not control copyright. Those thus making or running the covered works
		171	+for you must do so exclusively on your behalf, under your direction
		172	+and control, on terms that prohibit them from making any copies of
		173	+your copyrighted material outside their relationship with you.
		174	+
		175	+ Conveying under any other circumstances is permitted solely under
		176	+the conditions stated below. Sublicensing is not allowed; section 10
		177	+makes it unnecessary.
		178	+
		179	+ 3. Protecting Users' Legal Rights From Anti-Circumvention Law.
		180	+
		181	+ No covered work shall be deemed part of an effective technological
		182	+measure under any applicable law fulfilling obligations under article
		183	+11 of the WIPO copyright treaty adopted on 20 December 1996, or
		184	+similar laws prohibiting or restricting circumvention of such
		185	+measures.
		186	+
		187	+ When you convey a covered work, you waive any legal power to forbid
		188	+circumvention of technological measures to the extent such circumvention
		189	+is effected by exercising rights under this License with respect to
		190	+the covered work, and you disclaim any intention to limit operation or
		191	+modification of the work as a means of enforcing, against the work's
		192	+users, your or third parties' legal rights to forbid circumvention of
		193	+technological measures.
		194	+
		195	+ 4. Conveying Verbatim Copies.
		196	+
		197	+ You may convey verbatim copies of the Program's source code as you
		198	+receive it, in any medium, provided that you conspicuously and
		199	+appropriately publish on each copy an appropriate copyright notice;
		200	+keep intact all notices stating that this License and any
		201	+non-permissive terms added in accord with section 7 apply to the code;
		202	+keep intact all notices of the absence of any warranty; and give all
		203	+recipients a copy of this License along with the Program.
		204	+
		205	+ You may charge any price or no price for each copy that you convey,
		206	+and you may offer support or warranty protection for a fee.
		207	+
		208	+ 5. Conveying Modified Source Versions.
		209	+
		210	+ You may convey a work based on the Program, or the modifications to
		211	+produce it from the Program, in the form of source code under the
		212	+terms of section 4, provided that you also meet all of these conditions:
		213	+
		214	+ a) The work must carry prominent notices stating that you modified
		215	+ it, and giving a relevant date.
		216	+
		217	+ b) The work must carry prominent notices stating that it is
		218	+ released under this License and any conditions added under section
		219	+ 7. This requirement modifies the requirement in section 4 to
		220	+ "keep intact all notices".
		221	+
		222	+ c) You must license the entire work, as a whole, under this
		223	+ License to anyone who comes into possession of a copy. This
		224	+ License will therefore apply, along with any applicable section 7
		225	+ additional terms, to the whole of the work, and all its parts,
		226	+ regardless of how they are packaged. This License gives no
		227	+ permission to license the work in any other way, but it does not
		228	+ invalidate such permission if you have separately received it.
		229	+
		230	+ d) If the work has interactive user interfaces, each must display
		231	+ Appropriate Legal Notices; however, if the Program has interactive
		232	+ interfaces that do not display Appropriate Legal Notices, your
		233	+ work need not make them do so.
		234	+
		235	+ A compilation of a covered work with other separate and independent
		236	+works, which are not by their nature extensions of the covered work,
		237	+and which are not combined with it such as to form a larger program,
		238	+in or on a volume of a storage or distribution medium, is called an
		239	+"aggregate" if the compilation and its resulting copyright are not
		240	+used to limit the access or legal rights of the compilation's users
		241	+beyond what the individual works permit. Inclusion of a covered work
		242	+in an aggregate does not cause this License to apply to the other
		243	+parts of the aggregate.
		244	+
		245	+ 6. Conveying Non-Source Forms.
		246	+
		247	+ You may convey a covered work in object code form under the terms
		248	+of sections 4 and 5, provided that you also convey the
		249	+machine-readable Corresponding Source under the terms of this License,
		250	+in one of these ways:
		251	+
		252	+ a) Convey the object code in, or embodied in, a physical product
		253	+ (including a physical distribution medium), accompanied by the
		254	+ Corresponding Source fixed on a durable physical medium
		255	+ customarily used for software interchange.
		256	+
		257	+ b) Convey the object code in, or embodied in, a physical product
		258	+ (including a physical distribution medium), accompanied by a
		259	+ written offer, valid for at least three years and valid for as
		260	+ long as you offer spare parts or customer support for that product
		261	+ model, to give anyone who possesses the object code either (1) a
		262	+ copy of the Corresponding Source for all the software in the
		263	+ product that is covered by this License, on a durable physical
		264	+ medium customarily used for software interchange, for a price no
		265	+ more than your reasonable cost of physically performing this
		266	+ conveying of source, or (2) access to copy the
		267	+ Corresponding Source from a network server at no charge.
		268	+
		269	+ c) Convey individual copies of the object code with a copy of the
		270	+ written offer to provide the Corresponding Source. This
		271	+ alternative is allowed only occasionally and noncommercially, and
		272	+ only if you received the object code with such an offer, in accord
		273	+ with subsection 6b.
		274	+
		275	+ d) Convey the object code by offering access from a designated
		276	+ place (gratis or for a charge), and offer equivalent access to the
		277	+ Corresponding Source in the same way through the same place at no
		278	+ further charge. You need not require recipients to copy the
		279	+ Corresponding Source along with the object code. If the place to
		280	+ copy the object code is a network server, the Corresponding Source
		281	+ may be on a different server (operated by you or a third party)
		282	+ that supports equivalent copying facilities, provided you maintain
		283	+ clear directions next to the object code saying where to find the
		284	+ Corresponding Source. Regardless of what server hosts the
		285	+ Corresponding Source, you remain obligated to ensure that it is
		286	+ available for as long as needed to satisfy these requirements.
		287	+
		288	+ e) Convey the object code using peer-to-peer transmission, provided
		289	+ you inform other peers where the object code and Corresponding
		290	+ Source of the work are being offered to the general public at no
		291	+ charge under subsection 6d.
		292	+
		293	+ A separable portion of the object code, whose source code is excluded
		294	+from the Corresponding Source as a System Library, need not be
		295	+included in conveying the object code work.
		296	+
		297	+ A "User Product" is either (1) a "consumer product", which means any
		298	+tangible personal property which is normally used for personal, family,
		299	+or household purposes, or (2) anything designed or sold for incorporation
		300	+into a dwelling. In determining whether a product is a consumer product,
		301	+doubtful cases shall be resolved in favor of coverage. For a particular
		302	+product received by a particular user, "normally used" refers to a
		303	+typical or common use of that class of product, regardless of the status
		304	+of the particular user or of the way in which the particular user
		305	+actually uses, or expects or is expected to use, the product. A product
		306	+is a consumer product regardless of whether the product has substantial
		307	+commercial, industrial or non-consumer uses, unless such uses represent
		308	+the only significant mode of use of the product.
		309	+
		310	+ "Installation Information" for a User Product means any methods,
		311	+procedures, authorization keys, or other information required to install
		312	+and execute modified versions of a covered work in that User Product from
		313	+a modified version of its Corresponding Source. The information must
		314	+suffice to ensure that the continued functioning of the modified object
		315	+code is in no case prevented or interfered with solely because
		316	+modification has been made.
		317	+
		318	+ If you convey an object code work under this section in, or with, or
		319	+specifically for use in, a User Product, and the conveying occurs as
		320	+part of a transaction in which the right of possession and use of the
		321	+User Product is transferred to the recipient in perpetuity or for a
		322	+fixed term (regardless of how the transaction is characterized), the
		323	+Corresponding Source conveyed under this section must be accompanied
		324	+by the Installation Information. But this requirement does not apply
		325	+if neither you nor any third party retains the ability to install
		326	+modified object code on the User Product (for example, the work has
		327	+been installed in ROM).
		328	+
		329	+ The requirement to provide Installation Information does not include a
		330	+requirement to continue to provide support service, warranty, or updates
		331	+for a work that has been modified or installed by the recipient, or for
		332	+the User Product in which it has been modified or installed. Access to a
		333	+network may be denied when the modification itself materially and
		334	+adversely affects the operation of the network or violates the rules and
		335	+protocols for communication across the network.
		336	+
		337	+ Corresponding Source conveyed, and Installation Information provided,
		338	+in accord with this section must be in a format that is publicly
		339	+documented (and with an implementation available to the public in
		340	+source code form), and must require no special password or key for
		341	+unpacking, reading or copying.
		342	+
		343	+ 7. Additional Terms.
		344	+
		345	+ "Additional permissions" are terms that supplement the terms of this
		346	+License by making exceptions from one or more of its conditions.
		347	+Additional permissions that are applicable to the entire Program shall
		348	+be treated as though they were included in this License, to the extent
		349	+that they are valid under applicable law. If additional permissions
		350	+apply only to part of the Program, that part may be used separately
		351	+under those permissions, but the entire Program remains governed by
		352	+this License without regard to the additional permissions.
		353	+
		354	+ When you convey a copy of a covered work, you may at your option
		355	+remove any additional permissions from that copy, or from any part of
		356	+it. (Additional permissions may be written to require their own
		357	+removal in certain cases when you modify the work.) You may place
		358	+additional permissions on material, added by you to a covered work,
		359	+for which you have or can give appropriate copyright permission.
		360	+
		361	+ Notwithstanding any other provision of this License, for material you
		362	+add to a covered work, you may (if authorized by the copyright holders of
		363	+that material) supplement the terms of this License with terms:
		364	+
		365	+ a) Disclaiming warranty or limiting liability differently from the
		366	+ terms of sections 15 and 16 of this License; or
		367	+
		368	+ b) Requiring preservation of specified reasonable legal notices or
		369	+ author attributions in that material or in the Appropriate Legal
		370	+ Notices displayed by works containing it; or
		371	+
		372	+ c) Prohibiting misrepresentation of the origin of that material, or
		373	+ requiring that modified versions of such material be marked in
		374	+ reasonable ways as different from the original version; or
		375	+
		376	+ d) Limiting the use for publicity purposes of names of licensors or
		377	+ authors of the material; or
		378	+
		379	+ e) Declining to grant rights under trademark law for use of some
		380	+ trade names, trademarks, or service marks; or
		381	+
		382	+ f) Requiring indemnification of licensors and authors of that
		383	+ material by anyone who conveys the material (or modified versions of
		384	+ it) with contractual assumptions of liability to the recipient, for
		385	+ any liability that these contractual assumptions directly impose on
		386	+ those licensors and authors.
		387	+
		388	+ All other non-permissive additional terms are considered "further
		389	+restrictions" within the meaning of section 10. If the Program as you
		390	+received it, or any part of it, contains a notice stating that it is
		391	+governed by this License along with a term that is a further
		392	+restriction, you may remove that term. If a license document contains
		393	+a further restriction but permits relicensing or conveying under this
		394	+License, you may add to a covered work material governed by the terms
		395	+of that license document, provided that the further restriction does
		396	+not survive such relicensing or conveying.
		397	+
		398	+ If you add terms to a covered work in accord with this section, you
		399	+must place, in the relevant source files, a statement of the
		400	+additional terms that apply to those files, or a notice indicating
		401	+where to find the applicable terms.
		402	+
		403	+ Additional terms, permissive or non-permissive, may be stated in the
		404	+form of a separately written license, or stated as exceptions;
		405	+the above requirements apply either way.
		406	+
		407	+ 8. Termination.
		408	+
		409	+ You may not propagate or modify a covered work except as expressly
		410	+provided under this License. Any attempt otherwise to propagate or
		411	+modify it is void, and will automatically terminate your rights under
		412	+this License (including any patent licenses granted under the third
		413	+paragraph of section 11).
		414	+
		415	+ However, if you cease all violation of this License, then your
		416	+license from a particular copyright holder is reinstated (a)
		417	+provisionally, unless and until the copyright holder explicitly and
		418	+finally terminates your license, and (b) permanently, if the copyright
		419	+holder fails to notify you of the violation by some reasonable means
		420	+prior to 60 days after the cessation.
		421	+
		422	+ Moreover, your license from a particular copyright holder is
		423	+reinstated permanently if the copyright holder notifies you of the
		424	+violation by some reasonable means, this is the first time you have
		425	+received notice of violation of this License (for any work) from that
		426	+copyright holder, and you cure the violation prior to 30 days after
		427	+your receipt of the notice.
		428	+
		429	+ Termination of your rights under this section does not terminate the
		430	+licenses of parties who have received copies or rights from you under
		431	+this License. If your rights have been terminated and not permanently
		432	+reinstated, you do not qualify to receive new licenses for the same
		433	+material under section 10.
		434	+
		435	+ 9. Acceptance Not Required for Having Copies.
		436	+
		437	+ You are not required to accept this License in order to receive or
		438	+run a copy of the Program. Ancillary propagation of a covered work
		439	+occurring solely as a consequence of using peer-to-peer transmission
		440	+to receive a copy likewise does not require acceptance. However,
		441	+nothing other than this License grants you permission to propagate or
		442	+modify any covered work. These actions infringe copyright if you do
		443	+not accept this License. Therefore, by modifying or propagating a
		444	+covered work, you indicate your acceptance of this License to do so.
		445	+
		446	+ 10. Automatic Licensing of Downstream Recipients.
		447	+
		448	+ Each time you convey a covered work, the recipient automatically
		449	+receives a license from the original licensors, to run, modify and
		450	+propagate that work, subject to this License. You are not responsible
		451	+for enforcing compliance by third parties with this License.
		452	+
		453	+ An "entity transaction" is a transaction transferring control of an
		454	+organization, or substantially all assets of one, or subdividing an
		455	+organization, or merging organizations. If propagation of a covered
		456	+work results from an entity transaction, each party to that
		457	+transaction who receives a copy of the work also receives whatever
		458	+licenses to the work the party's predecessor in interest had or could
		459	+give under the previous paragraph, plus a right to possession of the
		460	+Corresponding Source of the work from the predecessor in interest, if
		461	+the predecessor has it or can get it with reasonable efforts.
		462	+
		463	+ You may not impose any further restrictions on the exercise of the
		464	+rights granted or affirmed under this License. For example, you may
		465	+not impose a license fee, royalty, or other charge for exercise of
		466	+rights granted under this License, and you may not initiate litigation
		467	+(including a cross-claim or counterclaim in a lawsuit) alleging that
		468	+any patent claim is infringed by making, using, selling, offering for
		469	+sale, or importing the Program or any portion of it.
		470	+
		471	+ 11. Patents.
		472	+
		473	+ A "contributor" is a copyright holder who authorizes use under this
		474	+License of the Program or a work on which the Program is based. The
		475	+work thus licensed is called the contributor's "contributor version".
		476	+
		477	+ A contributor's "essential patent claims" are all patent claims
		478	+owned or controlled by the contributor, whether already acquired or
		479	+hereafter acquired, that would be infringed by some manner, permitted
		480	+by this License, of making, using, or selling its contributor version,
		481	+but do not include claims that would be infringed only as a
		482	+consequence of further modification of the contributor version. For
		483	+purposes of this definition, "control" includes the right to grant
		484	+patent sublicenses in a manner consistent with the requirements of
		485	+this License.
		486	+
		487	+ Each contributor grants you a non-exclusive, worldwide, royalty-free
		488	+patent license under the contributor's essential patent claims, to
		489	+make, use, sell, offer for sale, import and otherwise run, modify and
		490	+propagate the contents of its contributor version.
		491	+
		492	+ In the following three paragraphs, a "patent license" is any express
		493	+agreement or commitment, however denominated, not to enforce a patent
		494	+(such as an express permission to practice a patent or covenant not to
		495	+sue for patent infringement). To "grant" such a patent license to a
		496	+party means to make such an agreement or commitment not to enforce a
		497	+patent against the party.
		498	+
		499	+ If you convey a covered work, knowingly relying on a patent license,
		500	+and the Corresponding Source of the work is not available for anyone
		501	+to copy, free of charge and under the terms of this License, through a
		502	+publicly available network server or other readily accessible means,
		503	+then you must either (1) cause the Corresponding Source to be so
		504	+available, or (2) arrange to deprive yourself of the benefit of the
		505	+patent license for this particular work, or (3) arrange, in a manner
		506	+consistent with the requirements of this License, to extend the patent
		507	+license to downstream recipients. "Knowingly relying" means you have
		508	+actual knowledge that, but for the patent license, your conveying the
		509	+covered work in a country, or your recipient's use of the covered work
		510	+in a country, would infringe one or more identifiable patents in that
		511	+country that you have reason to believe are valid.
		512	+
		513	+ If, pursuant to or in connection with a single transaction or
		514	+arrangement, you convey, or propagate by procuring conveyance of, a
		515	+covered work, and grant a patent license to some of the parties
		516	+receiving the covered work authorizing them to use, propagate, modify
		517	+or convey a specific copy of the covered work, then the patent license
		518	+you grant is automatically extended to all recipients of the covered
		519	+work and works based on it.
		520	+
		521	+ A patent license is "discriminatory" if it does not include within
		522	+the scope of its coverage, prohibits the exercise of, or is
		523	+conditioned on the non-exercise of one or more of the rights that are
		524	+specifically granted under this License. You may not convey a covered
		525	+work if you are a party to an arrangement with a third party that is
		526	+in the business of distributing software, under which you make payment
		527	+to the third party based on the extent of your activity of conveying
		528	+the work, and under which the third party grants, to any of the
		529	+parties who would receive the covered work from you, a discriminatory
		530	+patent license (a) in connection with copies of the covered work
		531	+conveyed by you (or copies made from those copies), or (b) primarily
		532	+for and in connection with specific products or compilations that
		533	+contain the covered work, unless you entered into that arrangement,
		534	+or that patent license was granted, prior to 28 March 2007.
		535	+
		536	+ Nothing in this License shall be construed as excluding or limiting
		537	+any implied license or other defenses to infringement that may
		538	+otherwise be available to you under applicable patent law.
		539	+
		540	+ 12. No Surrender of Others' Freedom.
		541	+
		542	+ If conditions are imposed on you (whether by court order, agreement or
		543	+otherwise) that contradict the conditions of this License, they do not
		544	+excuse you from the conditions of this License. If you cannot convey a
		545	+covered work so as to satisfy simultaneously your obligations under this
		546	+License and any other pertinent obligations, then as a consequence you may
		547	+not convey it at all. For example, if you agree to terms that obligate you
		548	+to collect a royalty for further conveying from those to whom you convey
		549	+the Program, the only way you could satisfy both those terms and this
		550	+License would be to refrain entirely from conveying the Program.
		551	+
		552	+ 13. Use with the GNU Affero General Public License.
		553	+
		554	+ Notwithstanding any other provision of this License, you have
		555	+permission to link or combine any covered work with a work licensed
		556	+under version 3 of the GNU Affero General Public License into a single
		557	+combined work, and to convey the resulting work. The terms of this
		558	+License will continue to apply to the part which is the covered work,
		559	+but the special requirements of the GNU Affero General Public License,
		560	+section 13, concerning interaction through a network will apply to the
		561	+combination as such.
		562	+
		563	+ 14. Revised Versions of this License.
		564	+
		565	+ The Free Software Foundation may publish revised and/or new versions of
		566	+the GNU General Public License from time to time. Such new versions will
		567	+be similar in spirit to the present version, but may differ in detail to
		568	+address new problems or concerns.
		569	+
		570	+ Each version is given a distinguishing version number. If the
		571	+Program specifies that a certain numbered version of the GNU General
		572	+Public License "or any later version" applies to it, you have the
		573	+option of following the terms and conditions either of that numbered
		574	+version or of any later version published by the Free Software
		575	+Foundation. If the Program does not specify a version number of the
		576	+GNU General Public License, you may choose any version ever published
		577	+by the Free Software Foundation.
		578	+
		579	+ If the Program specifies that a proxy can decide which future
		580	+versions of the GNU General Public License can be used, that proxy's
		581	+public statement of acceptance of a version permanently authorizes you
		582	+to choose that version for the Program.
		583	+
		584	+ Later license versions may give you additional or different
		585	+permissions. However, no additional obligations are imposed on any
		586	+author or copyright holder as a result of your choosing to follow a
		587	+later version.
		588	+
		589	+ 15. Disclaimer of Warranty.
		590	+
		591	+ THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
		592	+APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
		593	+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
		594	+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
		595	+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
		596	+PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
		597	+IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
		598	+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
		599	+
		600	+ 16. Limitation of Liability.
		601	+
		602	+ IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
		603	+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
		604	+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
		605	+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
		606	+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
		607	+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
		608	+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
		609	+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
		610	+SUCH DAMAGES.
		611	+
		612	+ 17. Interpretation of Sections 15 and 16.
		613	+
		614	+ If the disclaimer of warranty and limitation of liability provided
		615	+above cannot be given local legal effect according to their terms,
		616	+reviewing courts shall apply local law that most closely approximates
		617	+an absolute waiver of all civil liability in connection with the
		618	+Program, unless a warranty or assumption of liability accompanies a
		619	+copy of the Program in return for a fee.
		620	+
		621	+ END OF TERMS AND CONDITIONS
		622	+
		623	+ How to Apply These Terms to Your New Programs
		624	+
		625	+ If you develop a new program, and you want it to be of the greatest
		626	+possible use to the public, the best way to achieve this is to make it
		627	+free software which everyone can redistribute and change under these terms.
		628	+
		629	+ To do so, attach the following notices to the program. It is safest
		630	+to attach them to the start of each source file to most effectively
		631	+state the exclusion of warranty; and each file should have at least
		632	+the "copyright" line and a pointer to where the full notice is found.
		633	+
		634	+ <one line to give the program's name and a brief idea of what it does.>
		635	+ Copyright (C) <year> <name of author>
		636	+
		637	+ This program is free software: you can redistribute it and/or modify
		638	+ it under the terms of the GNU General Public License as published by
		639	+ the Free Software Foundation, either version 3 of the License, or
		640	+ (at your option) any later version.
		641	+
		642	+ This program is distributed in the hope that it will be useful,
		643	+ but WITHOUT ANY WARRANTY; without even the implied warranty of
		644	+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
		645	+ GNU General Public License for more details.
		646	+
		647	+ You should have received a copy of the GNU General Public License
		648	+ along with this program. If not, see <http://www.gnu.org/licenses/>.
		649	+
		650	+Also add information on how to contact you by electronic and paper mail.
		651	+
		652	+ If the program does terminal interaction, make it output a short
		653	+notice like this when it starts in an interactive mode:
		654	+
		655	+ <program> Copyright (C) <year> <name of author>
		656	+ This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
		657	+ This is free software, and you are welcome to redistribute it
		658	+ under certain conditions; type `show c' for details.
		659	+
		660	+The hypothetical commands `show w' and `show c' should show the appropriate
		661	+parts of the General Public License. Of course, your program's commands
		662	+might be different; for a GUI interface, you would use an "about box".
		663	+
		664	+ You should also get your employer (if you work as a programmer) or school,
		665	+if any, to sign a "copyright disclaimer" for the program, if necessary.
		666	+For more information on this, and how to apply and follow the GNU GPL, see
		667	+<http://www.gnu.org/licenses/>.
		668	+
		669	+ The GNU General Public License does not permit incorporating your program
		670	+into proprietary programs. If your program is a subroutine library, you
		671	+may consider it more useful to permit linking proprietary applications with
		672	+the library. If this is what you want to do, use the GNU Lesser General
		673	+Public License instead of this License. But first, please read
		674	+<http://www.gnu.org/philosophy/why-not-lgpl.html>.

README.md 0 → 100644

View file @47b5f8d

		1	+++ a/README.md
		1	+CLI Library
		2	+===========
		3	+
		4	+Library to build a real-time serial (or network) command-line interface (CLI) to
		5	+configure or control your Arduino or compatible microcontroller.
		6	+
		7	+This is Version 1.0, the latest version, documentation and bugtracker are
		8	+available on my [GitLab instance](https://gitlab.lindenaar.net/arduino/CLI)
		9	+
		10	+Copyright (c) 2019 Frederik Lindenaar. free for distribution under the
		11	+GNU License, see [below](#license)
		12	+
		13	+
		14	+Introduction
		15	+------------
		16	+Frequently need to interact with a microcontroller to, for example:
		17	+ * see what's stored in the embedded or an I2C EEPROM
		18	+ * check that all I2C devices are detected and responding
		19	+ * check or set a connected real-time clock
		20	+ * check or set configuration options (I don't hard-code config)
		21	+
		22	+Since I don't like reprogramming the microcontroller every time this is needed,
		23	+I wrote this library to provide a Command Line Interface over a Serial / USB
		24	+line. The library includes a number of commands that can be included where
		25	+applicable (which I expect will grow over time as I build more) so that it can
		26	+be used as a toolbox to start your development without having to worry about
		27	+stuff that could be standard. At this moment it includes the following commands:
		28	+ * `eeprom_dump` to display the contents of the built-in EEPROM
		29	+ * `i2c_scan` to scan the I2C bus for slave devices
		30	+ * `i2c_dump` to display the contents of I2C attached EEPROM or Memory
		31	+ * `reset` to restart the microcontroller (software reset)
		32	+ * `help` to display available commands and provided help on how to use them
		33	+
		34	+See below how to use the Library, to get an idea on how to use the library,
		35	+have a look at the examples included:
		36	+ * _Blink_: control the Blink example (using the built-in LED) using a
		37	+ Serial/USB console to change its blink rate or turn it on or off
		38	+ * _Debug_: CLI with the built-in debug commands listed above
		39	+ * _DS1307RTC_: CLI to read/set an DS1307 Real-Time Clock module (includes
		40	+ the built-in commands to access a module's NVRAM and EEPROM)
		41	+
		42	+
		43	+Download / Installation
		44	+-----------------------
		45	+At this moment this library is not yet available directly from the Arduino IDE
		46	+but has to be installed manually. For this, download the latest distribution
		47	+.zip file and install it using the following links:
		48	+ * From my GitLab instance, download to your computer the
		49	+ [Latest .zip archive](https://gitlab.lindenaar.net/arduino/CLI/repository/archive.zip)
		50	+ * Follow the documentation for the Arduino IDE on
		51	+ [importing a .zip Library](https://www.arduino.cc/en/Guide/Libraries#toc4).
		52	+ Alternatively, you can also extract the downloaded .zip and follow the steps
		53	+ for [manual Installation](https://www.arduino.cc/en/Guide/Libraries#toc5)
		54	+
		55	+You can also use `git` to checkout the latest version from my repository with
		56	+
		57	+```
		58	+ git clone https://gitlab.lindenaar.net/arduino/CLI.git
		59	+```
		60	+
		61	+so that it is easy to upgrade in the future. To find where to checkout check the
		62	+guide for [manual Installation](https://www.arduino.cc/en/Guide/Libraries#toc5).
		63	+
		64	+
		65	+Using the library
		66	+-----------------
		67	+Before adding this library to your code, it is important to realize that by
		68	+adding the CLI you are builing a so-called real-time system. The microcontroller
		69	+should be able to perform it's main task (normally not responding to Serial/USB
		70	+input) and in the background listen to commands given through the CLI. As most
		71	+microcontrollers have only a single CPU and no OS that can multitask, all logic
		72	+is handled from the main `loop()` function. As a consequence, one should avoid
		73	+writing code that waits (e.g. using the `delay()` function) but instead create
		74	+a loop that does not wait/block but determines whether to do something and if
		75	+not moves on to the next task.
		76	+
		77	+### Writing a real-time (i.e. non-blocking) loop
		78	+Looking at the Arduino IDE's standard Blink example (probably the starting point
		79	+for most when starting with the platform), you see the following code in `loop`:
		80	+
		81	+~~~
		82	+// the loop function runs over and over again forever
		83	+void loop() {
		84	+ digitalWrite(LED_BUILTIN, HIGH); // turn LED on (HIGH is the voltage level)
		85	+ delay(1000); // wait for a second
		86	+ digitalWrite(LED_BUILTIN, LOW); // turn LED off by making the voltage LOW
		87	+ delay(1000); // wait for a second
		88	+}
		89	+~~~
		90	+
		91	+While this is perfectly fine code when the microcontroller has nothing else to
		92	+do, for a background CLI this would cause 1 second delays between each check for
		93	+input (ignoring more complex interrupt-driven approaches, which have their own
		94	+challenges). The key for making this loop non-blocking is to change it so that
		95	+it no longer waits but each time checks if it needs to change the LED status
		96	+instead, like in the example below:
		97	+
		98	+~~~
		99	+// variable to be preserved
		100	+unsigned long last_blink = 0;
		101	+
		102	+// the loop function runs over and over again forever
		103	+void loop() {
		104	+ // millis() will wrap every 49 days, below code is wrap-proof
		105	+ if (millis() - last_blink > 1000) { // last_blink was longer ago than delay?
		106	+ last_blink = millis(); // led state will change, store when
		107	+ if(digitalRead(LED_BUILTIN)) { // check if the LED is on or off
		108	+ digitalWrite(LED_BUILTIN, LOW); // turn LED off by making the pin LOW
		109	+ } else {
		110	+ digitalWrite(LED_BUILTIN, HIGH); // turn LED on by making the pin HIGH
		111	+ }
		112	+ }
		113	+}
		114	+~~~
		115	+
		116	+This code uses the Arduino platform function `millis()` to obtain how long the
		117	+code is running (in milliseconds) and keeps track of when the LED state changed
		118	+last in variable `last_blink` (stored outside the loop so it is preserved).
		119	+The loop now simply checks every time whether the last blink was more than 1000
		120	+milliseconds ago and if so changes the LED state, otherwise it does nothing.
		121	+Please note that the above code was kept as much in line with the original Blink
		122	+example though could also be written as:
		123	+
		124	+~~~
		125	+// variable to be preserved
		126	+unsigned long last_blink = 0;
		127	+
		128	+// the loop function runs over and over again forever
		129	+void loop() {
		130	+ // millis() will wrap every 49 days, below code is wrap-proof
		131	+ if (millis() - last_blink > 1000) { // last_blink was longer ago than delay?
		132	+ last_blink = millis(); // led state will change, store when
		133	+ digitalWrite(LED_BUILTIN, !digitalRead(LED_BUILTIN)); // invert LED PIN
		134	+ }
		135	+}
		136	+~~~
		137	+
		138	+Once the loop of your code is non-blocking, the CLI can be added to your Sketch.
		139	+
		140	+### Adding the CLI to a Sketch
		141	+Adding the CLI to your sketch is pretty straightforward, first include `CLI.h`
		142	+at the top of your sketch like this:
		143	+
		144	+~~~
		145	+#include <CLI.h>
		146	+~~~
		147	+
		148	+Next instantiate the CLI object by adding the following above (and outside) your
		149	+`setup()` and `loop()` functions:
		150	+
		151	+~~~
		152	+// Initialize the Command Line Interface
		153	+CLI CLI(Serial); // Initialize the CLI, telling it to attach to Serial
		154	+~~~
		155	+
		156	+Directly under the instantation of the `CLI` object commands can be instantiated
		157	+(added) like is shown below for the built-in Help command:
		158	+
		159	+~~~
		160	+Help_Command Help(CLI); // Initialize/Register (built-in) help command
		161	+~~~
		162	+
		163	+The constructor of each command requires a `CLI` to register with to make the
		164	+implemented command available in the CLI.
		165	+Next in your `loop()`, place the following logic at the top:
		166	+
		167	+~~~
		168	+// handle CLI, if this returns true a command is running so skip code block
		169	+if (!CLI.process()) {
		170	+ // Code to run when no command is executing, make sure it is non-blocking...
		171	+}
		172	+// Code to execute every loop goes here, make sure it is non-blocking...
		173	+~~~
		174	+
		175	+The `CLI.process()` method handles the Command Line Interpreter; it responds to
		176	+user input, parses the command and executes the command code. To ensure that
		177	+this is also non-blocking, each of these steps is executed in smaller chunks so
		178	+that your main logic can be intertwined with the execution of the CLI logic. The
		179	+`CLI.process()` method will return `true` if a command is still executing so by
		180	+placing logic inside the `if() { ... }` block, you ensure it only runs when the
		181	+CLI is not doing anything while if you put it outside the block it will always
		182	+be executed. This can also be used to add an LED indicator to display whether
		183	+the CLI is executing as is shown in the below full sketch example (which shows
		184	+how a basic full implementation would look like):
		185	+
		186	+~~~
		187	+#include <CLI.h>
		188	+
		189	+// Initialize the Command Line Interface
		190	+CLI CLI(Serial); // Initialize the CLI, telling it to attach to Serial
		191	+Help_Command Help(CLI); // Initialize/Register (built-in) help command
		192	+
		193	+
		194	+// the setup function runs once when you reset or power the board
		195	+void setup() {
		196	+ // Initialize digital pin LED_BUILTIN as an output.
		197	+ pinMode(LED_BUILTIN, OUTPUT);
		198	+
		199	+ // Initialize the Serial port for the CLI
		200	+ while (!Serial); // For Leonardo: wait for serial USB to connect
		201	+ Serial.begin(9600);
		202	+}
		203	+
		204	+
		205	+// the loop function runs over and over again forever
		206	+void loop() {
		207	+ // handle CLI, if this returns true a command is running so skip code block
		208	+ if (CLI.process()) {
		209	+ digitalWrite(LED_BUILTIN, HIGH); // turn LED on when processing CLI command
		210	+ } else {
		211	+ digitalWrite(LED_BUILTIN, LOW); // turn LED off when CLI command not active
		212	+ // Code to run when no command is executing, make sure it is non-blocking...
		213	+ }
		214	+ // Code to execute every loop goes here, make sure it is non-blocking...
		215	+}
		216	+~~~
		217	+
		218	+You can run the above code by creating a new sketch and replacing its contents
		219	+with the full example above. Please also have a look at the examples provided as
		220	+they give a better view on what can be done and how to include a CLI in your
		221	+sketch.
		222	+
		223	+#### CLI on the Serial port
		224	+As you can see in the above example, the CLI object is initiated and on `Serial`
		225	+and used to instantiate the `Help_Command` while `Serial.begin()` is only called
		226	+from setup() (i.e. afterwards). Due to the way the initialization of the Arduino
		227	+platform works, it is not possible to use `Serial.begin()` before `setup()` is
		228	+called as things like interrupts and other boot-strap initialization (including
		229	+that of the Serial port) has not taken place yet. For this reason the CLI object
		230	+cannot initialize a `Serial` port but you have to do this from your `setup()`
		231	+routine (which doesn't really matter and also gives you full control over it)
		232	+but should not be forgotten (as the CLI won't work then).
		233	+Please note that due to this it is also not possible to use `Serial.print()` in
		234	+a constructor (this has nothing do to with this library but is a quirk of the
		235	+Arduino platform).
		236	+
		237	+#### CLI object parameters
		238	+The CLI object supports printing a banner upon startup and allows to configure
		239	+the defaults prompt ( `> `). To reduce the memory usage, the passed string for
		240	+either must be stored in `PROGMEM` (program memory, i.e. with the program in
		241	+Flash). Both parameters can be passed to the constructor when initializing the
		242	+`CLI` object like this:
		243	+
		244	+~~~
		245	+const char CLI_banner[] PROGMEM = "My Microcontroller v1.0 CLI";
		246	+const char CLI_prompt[] PROGMEM = "mm> ";
		247	+CLI CLI(Serial, CLI_banner, CLI_prompt);
		248	+~~~
		249	+
		250	+Currently both must hence be hardcoded static strings and there is no way to
		251	+make them dynamic or change them. This is a conscious design choice to reduce
		252	+the size of the code and the memory it requires. In case you have a good use
		253	+case to reconsider this decision, let's discuss and for that please do
		254	+(raise an issue here)[https://gitlab.lindenaar.net/arduino/CLI/issues].
		255	+
		256	+#### CLI is a `Stream`
		257	+The CLI Object implements a Stream so it can be used as well to interact with
		258	+the user, both from a command as well as from your main loop. Besides the CLI
		259	+implementation described in this document and the `print()` family of functions,
		260	+it also provides:
		261	+ * `print_P (const char *str PROGMEM)` to print a string stored in `PROGMEM`
		262	+ * `print2digits(uint8_t num, char filler = '0', uint8_t base=10)`
		263	+ to print a number with at least 2 digits (useful for `HEX` bytes)
		264	+ * `print_mem(uint16_t addr, const uint8_t buff[], uint8_t len, uint8_t width=16)`
		265	+ to dump a memory block in HEX and ASCII (`addr` is the startaddress to print)
		266	+
		267	+
		268	+### Implementing a Command
		269	+CLI commands are implemented as separate classes that register themselves with
		270	+the CLI upon instantiation. The actions to implement for a command are:
		271	+ 1. instantiate - the command's class is instantiated and registers with a CLI
		272	+ 2. set parameters - the command parses the user's parameters for the execution
		273	+ 3. execute - the command performs it's tasks using the parameters provided.
		274	+
		275	+To implement a new CLI command, one should inherit from `CLI_Command`
		276	+
		277	+~~~
		278	+class CLI_Command {
		279	+ public:
		280	+ CLI_Command(CLI &cli, const char *command PROGMEM,
		281	+ const char *description PROGMEM,
		282	+ const char *help PROGMEM = NULL);
		283	+ virtual bool setparams(const char *params);
		284	+ virtual bool execute(CLI &cli) = 0;
		285	+};
		286	+~~~
		287	+
		288	+and implement it's public methods. At least a constructor (calling the one from
		289	+`CLI_Command`) and the `execute()` method must be implemented. The class has a
		290	+default implementation for the `setparams()` method that accepts no parameters
		291	+that can be used for commands that do need parameters. The details of the
		292	+implementation steps are covered in the next sections to demonstrate how to
		293	+implement a "hello" command accepting a parameter and printing that.
		294	+
		295	+#### Implementation (Class Definition)
		296	+The first step for the implementation of our "hello" command is to define a
		297	+class `Hello_Command` inheriting from `CLI_Command`. In this case we implement
		298	+all three methods as we want to accept parameter(s) and need the private
		299	+variable `_params` to store it in `setparams()` to be used by `execute()`. The
		300	+definition of this basic class looks like:
		301	+
		302	+~~~
		303	+class Hello_Command : CLI_Command {
		304	+ const char *_params;
		305	+ public:
		306	+ Hello_Command(CLI &cli);
		307	+ bool setparams(const char *params);
		308	+ bool execute(CLI &cli);
		309	+};
		310	+~~~
		311	+
		312	+Although it is possible to define the method in the definition, in this example
		313	+they will be defined separately first. See the full code at the end of this
		314	+section that implements the methods inline.
		315	+
		316	+#### Instantiate (Class constructor)
		317	+The implementation of the constructor can be very simple; call the constructor
		318	+of `CLI_Command` with the following parameters:
		319	+ 1. instance of `CLI` class to register with (should be passed as parameter)
		320	+ 2. (static) string in `PROGMEM` with the name of the command
		321	+ 3. (static) string in `PROGMEM` with a short (1-line) command description
		322	+ 4. (static) string in `PROGMEM` with additional usage information
		323	+
		324	+below the implementation of the example "hello" command with empty constructor
		325	+(as no functional initiation is required) only calling the parent `CLI_Command`
		326	+with the above parameters:
		327	+
		328	+~~~
		329	+Hello_Command::Hello_Command(CLI &cli) : CLI_Command(&cli,
		330	+ PSTR("hello"),
		331	+ PSTR("Print an \"Hello\" greeting message"),
		332	+ PSTR("Usage:\thello <name>\n"
		333	+ "Where:\t<name>\ta string to include in the greeting")) { };
		334	+~~~
		335	+
		336	+The above uses the `PSTR()` macro to inline define the static strings for the
		337	+command name, description and help text. These normally are static and hence
		338	+hardcoded. The base implementation of the `Command` class takes care of storing
		339	+the references and making them available. It will also register the command with
		340	+the `CLI` instance provided. As already mentioned, the library assumes these are
		341	+in `PROGMEM` so please make sure your sketch stores them there.
		342	+
		343	+#### Set parameters (`setparams(const char *params)` method)
		344	+When the user invokes a command, the `setparams()` method is called with the
		345	+parameters the user provided after the command. This allows the command to
		346	+parse the parameters provided and do whatever is necessary for the command to
		347	+use this information (i.e. store it in an efficient way for `execute()`).
		348	+
		349	+The `setparams()` method is always called once when the user enters a command so
		350	+that it can ensure that everything is ready for the command's `execute()` method
		351	+to be invoked. It should return `true` in case the parameters are valid. In case
		352	+`setparams()` returns `false`, the execution of the command is aborted and its
		353	+`execute()` is never called but a standard error message is given instead.
		354	+
		355	+The `params` provided is a pointer to the start of the parameters with trailing
		356	+spaces removed and terminated with a `char(0)`. In case no (or only whitespace)
		357	+parameters were provided, this method is called with `NULL` so an Implementation
		358	+does not have to check for empty strings. As the CLI should not block the main
		359	+flow, make sure the parsing is efficient and keep it simple so that this method
		360	+(which is only called once for each command) does not take long.
		361	+
		362	+A very simple implementation for `setparams()` is provided below for our `hello`
		363	+command. This simply stores the pointer of the parameter string provided an will
		364	+result in a `true` result in case a parameter is provided or a `false` result
		365	+when the user did not provide any parameters.
		366	+
		367	+~~~
		368	+bool Hello_Command::setparams(const char *params) {
		369	+ _params = params;
		370	+ return (params);
		371	+}
		372	+~~~
		373	+
		374	+Often the parse will more complex as it is needs to parse the string provided.
		375	+The design choice to have this implemented in the command is that this provides
		376	+the greatest flexibility and does not assume anything w.r.t. how or which
		377	+parameters are passed. The library does include a number of support functions
		378	+that can be used to parse parameters and encode them in flags.
		379	+
		380	+Please note that any attribute / variable used to store parameters are global
		381	+(part of the object memory) so will eat up ram. Use them wisely so you don't
		382	+run out of RAM on the smaller Arduino platforms that have only 2Kb or RAM.
		383	+
		384	+#### Execute logic (`execute(CLI &cli)` method)
		385	+The `execute()` method contains the actual implementation of the command. It is
		386	+called with a reference to the `CLI` so that there is no need to store that in
		387	+the object. To support a real-time implementation even if the command needs a
		388	+longer time (or is waiting), the implementation can return `true` to pause the
		389	+current invocation of the `execute` method and will be called in the next main
		390	+`loop()` cycle again. This allows for returning to the main loop in between of
		391	+waiting or execution of the command so that the main loop can continue as well.
		392	+
		393	+Before `execute()` is the first time, `setparams()` is called once to process
		394	+parameters from the user and perform initialization or setup needed. As long
		395	+as `execute()` returns `true` it will continue to be invoked again until it
		396	+returns `false` to signal that the command's execution is complete. The Command
		397	+Line Interface will only process user input again when the command is completed
		398	+(so a command can also prompt the user for additional input)
		399	+
		400	+Below the implementation of the `hello` command, which is pretty simple as it
		401	+only prints "Hello" (stored in `PROGMEM` followed by the string the user
		402	+provided. It then returns `false` to signal to the `CLI` that it is done.
		403	+
		404	+~~~
		405	+bool Hello_Command::execute(CLI &cli) {
		406	+ cli.print_P(PSTR("Hello "));
		407	+ cli.println(_params);
		408	+ return false;
		409	+}
		410	+~~~
		411	+
		412	+Commands can be as complex as needed. For more extensive examples, please have a
		413	+look at the provided examples and built-in commands in `Commands.cpp`.
		414	+
		415	+#### Full Example Sketch for the Hello command
		416	+Below the full example sketch built up in the previous sections with the methods
		417	+implemented inline:
		418	+
		419	+~~~
		420	+#include <CLI.h>
		421	+
		422	+class Hello_Command : CLI_Command {
		423	+ const char *_params;
		424	+ public:
		425	+ Hello_Command(CLI &cli) :
		426	+ CLI_Command(cli,
		427	+ PSTR("hello"),
		428	+ PSTR("Print an \"Hello\" greeting message"),
		429	+ PSTR("Usage:\thello <name>\n"
		430	+ "Where:\t<name>\tstring to include in greeting")) { };
		431	+ bool setparams(const char *params) {
		432	+ _params = params;
		433	+ return (params);
		434	+ }
		435	+ bool execute(CLI &cli) {
		436	+ cli.print_P(PSTR("Hello "));
		437	+ cli.println(_params);
		438	+ return false;
		439	+ }
		440	+};
		441	+
		442	+// Initialize the Command Line Interface
		443	+const char CLI_banner[] PROGMEM = "Hello CLI v1.0";
		444	+CLI CLI(Serial, CLI_banner); // Initialize CLI, telling it to attach to Serial
		445	+Hello_Command Hello(CLI); // Initialize/Register above defined hello command
		446	+Help_Command Help(CLI); // Initialize/Register (built-in) help command
		447	+
		448	+
		449	+// the setup function runs once when you reset or power the board
		450	+void setup() {
		451	+ // Initialize digital pin LED_BUILTIN as an output.
		452	+ pinMode(LED_BUILTIN, OUTPUT);
		453	+
		454	+ // Initialize the Serial port for the CLI
		455	+ while (!Serial); // For Leonardo: wait for serial USB to connect
		456	+ Serial.begin(9600);
		457	+}
		458	+
		459	+
		460	+// the loop function runs over and over again forever
		461	+void loop() {
		462	+ // handle CLI, if this returns true a command is running so skip code block
		463	+ if (CLI.process()) {
		464	+ digitalWrite(LED_BUILTIN, HIGH); // turn LED on when processing CLI command
		465	+ } else {
		466	+ digitalWrite(LED_BUILTIN, LOW); // turn LED off when CLI command not active
		467	+ // Code to run when no command is executing, make sure it is non-blocking...
		468	+ }
		469	+ // Code to execute every loop goes here, make sure it is non-blocking...
		470	+}
		471	+~~~
		472	+
		473	+I hope this clarifies how this library can and should be used. In case you find
		474	+any issues with the documentation, code or examples, please do raise an issue
		475	+[here](https://gitlab.lindenaar.net/arduino/CLI/issues).
		476	+
		477	+
		478	+### Parser Support Functions
		479	+The library contains a number of support functions to ease with building a
		480	+parser for command parameters. These still need to be documented but can be found
		481	+already in `CLI_Utils.cpp` within the library and are used by the built-in
		482	+commands found in `Commands.cpp` and exampled included.
		483	+
		484	+
		485	+<a name="license">License</a>
		486	+=============================
		487	+This library, documentation and examples are free software: you can redistribute
		488	+them and/or modify them under the terms of the GNU General Public License as
		489	+published by the Free Software Foundation, either version 3 of the License, or
		490	+(at your option) any later version.
		491	+
		492	+This script, documentation and configuration examples are distributed in the
		493	+hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
		494	+warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
		495	+General Public License for more details.
		496	+
		497	+You should have received a copy of the GNU General Public License along with
		498	+this program. If not, download it from <http://www.gnu.org/licenses/>.
		499	+

examples/Blink/Blink.ino 0 → 100644

View file @47b5f8d

		1	+++ a/examples/Blink/Blink.ino
		1	+/*
		2	+ Blink.ino - CLI library sample implementing a CLI for the Blink sample code
		3	+
		4	+ Version 1.0, latest version, documentation and bugtracker available at:
		5	+ https://gitlab.lindenaar.net/arduino/CLI
		6	+
		7	+ Copyright (c) 2019 Frederik Lindenaar
		8	+
		9	+ This example shows how to build a simple command line to control the default
		10	+ Blink example of the Arduino IDE. This requires additional code to control
		11	+ the parameters (maintained within the C++ objects for the commands) as well
		12	+ as a different main loop logic to become a real-time process with a Command
		13	+ Line in te backgrouns while blinking and no longer using delay() for timing.
		14	+
		15	+ The implementation provides the following commands available through the
		16	+ Serial Monitor (available from the Tools menu of the Arduino IDE):
		17	+ - mode display and/or set the LED mode (either on, off or blink)
		18	+ - delay display and/or set the blinking delay for the led
		19	+ - faster double the blinking rate (half the delay)
		20	+ - slower half the blinking rate (double the delay)
		21	+ - help show the available commands and how to use (builtin command)
		22	+
		23	+ For each of the commands an CLI_Command derived class is implemented with :
		24	+ - Private variables to hold the internal state of the command
		25	+ - Object constructor to set default values
		26	+ - a setparams() method to handle parameters (when applicable)
		27	+ - a execute() method for the implementation of the command
		28	+ - Getter (and Setter) methods to access object state (where applicable)
		29	+
		30	+ This sketch is free software: you can redistribute it and/or modify it under
		31	+ the terms of version 3 of the GNU General Public License as published by the
		32	+ Free Software Foundation, or (at your option) a later version of the license.
		33	+
		34	+ This code is distributed in the hope that it will be useful but WITHOUT ANY
		35	+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
		36	+ A PARTICULAR PURPOSE. See the GNU General Public License for more details.
		37	+
		38	+ You should have received a copy of the GNU General Public License along with
		39	+ this program. If not, visit <http://www.gnu.org/licenses/> to download it.
		40	+*/
		41	+
		42	+#include <CLI.h>
		43	+
		44	+enum LED_MODE { OFF, ON, BLINKING }; // LED modes implemented/supported
		45	+
		46	+#define BLINK_MIN_DELAY 25 // min blink delay is 25ms
		47	+#define BLINK_MAX_DELAY 10000 // max blink delay is 10s
		48	+
		49	+// Convert macro to string (https://gcc.gnu.org/onlinedocs/cpp/Stringizing.html)
		50	+#define TO_STRING(val) #val
		51	+#define VAL_TO_STRING(val) TO_STRING(val)
		52	+
		53	+
		54	+// Store mode command parameters as static PROGMEM strings (needed below)
		55	+const char CMD_MODE_PARAM_ON[] PROGMEM = "on";
		56	+const char CMD_MODE_PARAM_OFF[] PROGMEM = "off";
		57	+const char CMD_MODE_PARAM_BLINK[] PROGMEM = "blink";
		58	+
		59	+// struct stored in PROGMEM to map the parameters for mode command to a value
		60	+const struct CLI_Command_Param Mode_Command_Parameters[] PROGMEM = {
		61	+ { CMD_MODE_PARAM_ON, ON, },
		62	+ { CMD_MODE_PARAM_OFF, OFF, },
		63	+ { CMD_MODE_PARAM_BLINK, BLINKING, },
		64	+ { NULL }
		65	+};
		66	+
		67	+
		68	+class Mode_Command : CLI_Command { // Implementation of the mode command
		69	+ LED_MODE _mode; // Private variable to store current mode
		70	+ public:
		71	+ Mode_Command(CLI &cli, LED_MODE mode = OFF) : // Constructor with default initial mode
		72	+ CLI_Command(cli, // CLI to register with
		73	+ PSTR("mode"), // Command name
		74	+ PSTR("Set and/or show LED mode"), // Description
		75	+ PSTR("Usage:\tmode [<led_mode>]\n" // Usage Help
		76	+ "where <led_mode> is one of:\n"
		77	+ "\ton\tturn LED on\n"
		78	+ "\toff\tturn LED off\n"
		79	+ "\tblink\tblink the LED\n")), _mode(mode) { };
		80	+ bool setparams(const char *params) { // Called once before execute to process parameters
		81	+ if (params) { // Check if we have parameters
		82	+ // Use the CLI_STR_parseParam_P utility function to parse the parameter
		83	+ const struct CLI_Command_Param *p = CLI_STR_parseParam_P(params, Mode_Command_Parameters);
		84	+ if (!p) return false; // return false in case of an invalid parameter
		85	+ _mode = pgm_read_word(&p->uint16); // set led_mode to the one of the parameter
		86	+ if (_mode != BLINKING) // ensure LED state == led_mode if not blinking
		87	+ digitalWrite(LED_BUILTIN, _mode == ON);
		88	+ }
		89	+ return true; // Return true in case of no or a valid parameter
		90	+ }
		91	+ bool execute(CLI &cli) { // Implementation, called as long as it returns true
		92	+ cli.print_P(PSTR("LED mode is ")); // Simply show the LED mode (need to do that always)
		93	+ cli.print_P((_mode == ON) ? PSTR("ON") :
		94	+ (_mode == OFF) ? PSTR("OFF") :
		95	+ (_mode == BLINKING) ? PSTR("blink") : PSTR("unknown"));
		96	+ return false; // return false as we're done
		97	+ }
		98	+ inline LED_MODE get() { // Getter for the mode
		99	+ return _mode;
		100	+ }
		101	+ inline void set(LED_MODE mode) { // Setter for the mode
		102	+ _mode = mode;
		103	+ }
		104	+};
		105	+
		106	+
		107	+class Delay_Command : CLI_Command { // Implementation of the delay command
		108	+ unsigned int _delay; // Private variable to store current delay
		109	+ public:
		110	+ Delay_Command(CLI &cli) : // Constructor
		111	+ CLI_Command(cli, // CLI to register with
		112	+ PSTR("delay"), // Command name
		113	+ PSTR("set and/or show LED blink delay"), // Description
		114	+ PSTR("Usage:\tdelay [<blink_delay>]\n" // Usage Help
		115	+ "\twhere <blink_delay> is the delay in milliseconds (integer between "
		116	+ VAL_TO_STRING(BLINK_MIN_DELAY) " and " VAL_TO_STRING(BLINK_MAX_DELAY) ")\n")) {
		117	+ _delay = 1000;
		118	+ };
		119	+ bool setparams(const char *params) { // Called once before execute to process parameters
		120	+ if (params) { // Check if we have parameters
		121	+ int d;
		122	+ params = CLI_STR_parseInt(params, d); // parse params using CLI_STR_parseInt utility function
		123	+ if (params && !*params) { // check if an int was found and reached end of params
		124	+ return set(d); // return true if all OK or false when not within range
		125	+ }
		126	+ return false; // return false if no int or more param input was found
		127	+ }
		128	+ return true; // return true in case of no or a valid parameter
		129	+ }
		130	+ bool execute(CLI &cli) { // Implementation, called as long as it returns true
		131	+ cli.print_P(PSTR("blink delay ")); // Simply show the blink delay (need to do that always)
		132	+ cli.print(_delay);
		133	+ cli.print_P(PSTR(" milliseconds\n"));
		134	+ return false; // return false as we're done
		135	+ }
		136	+ inline unsigned int get() { // Getter for the mode
		137	+ return _delay;
		138	+ }
		139	+ inline bool set(unsigned int d) { // Setter for the mode, checking it is within range
		140	+ if (d < BLINK_MIN_DELAY \|\| d > BLINK_MAX_DELAY)
		141	+ return false; // Return false if new value is out of bounds
		142	+ _delay = d; // store new value
		143	+ return true; // return true as new value is OK
		144	+ }
		145	+};
		146	+
		147	+
		148	+class Faster_Command : CLI_Command { // Implementation of the faster command
		149	+ Delay_Command &_delay; // Private variable to store delay command
		150	+ public:
		151	+ Faster_Command(CLI &cli, Delay_Command &delay) : // Constructor, requires delay command reference
		152	+ CLI_Command(cli, // CLI to register with
		153	+ PSTR("faster"), // Command name
		154	+ PSTR("Blink faster")), // Description, no Usage Help provided
		155	+ _delay(delay) { }; // Store reference to delay command, empty constructor
		156	+ // Please note: no parameters will be accepted (using default setparams() implementation)
		157	+ bool execute(CLI &cli) { // Implementation, called as long as it returns true
		158	+ if (_delay.set(_delay.get() / 2)) { // Half the blink time, returns false if outside range
		159	+ _delay.setparams(0); // clear _delay's parameters as we call it's execute() next
		160	+ _delay.execute(cli); // call _delay's execute() method to print the delay
		161	+ } else {
		162	+ cli.print_P(PSTR("Can't blink faster"));// print an error message if half blink delay is out of bounds
		163	+ }
		164	+ return false; // return false as we're done
		165	+ }
		166	+};
		167	+
		168	+
		169	+class Slower_Command : CLI_Command { // Implementation of the slower command
		170	+ Delay_Command &_delay; // Private variable to store delay command
		171	+ public:
		172	+ Slower_Command(CLI &cli, Delay_Command &delay) : // Constructor, requires delay command reference
		173	+ CLI_Command(cli, // CLI to register with
		174	+ PSTR("slower"), // Command name
		175	+ PSTR("Blink slower")), // Description, no Usage Help provided
		176	+ _delay(delay) { }; // Store reference to delay command, empty constructor
		177	+ // Please note: no parameters will be accepted (using default setparams() implementation)
		178	+ bool execute(CLI &cli) { // Implementation, called as long as it returns true
		179	+ if (_delay.set(_delay.get() * 2)) { // Half the blink time, returns false if outside range
		180	+ _delay.setparams(0); // clear _delay's parameters as we call it's execute() next
		181	+ _delay.execute(cli); // call _delay's execute() method to print the delay
		182	+ } else {
		183	+ cli.print_P(PSTR("Can't blink slower"));// print an error message if half blink delay is out of bounds
		184	+ }
		185	+ return false; // return false as we're done
		186	+ }
		187	+};
		188	+
		189	+
		190	+// Initialize the Blink Command Line Interface
		191	+const char banner[] PROGMEM = "Blink Sample CLI"; // Banner to show upon startup of the CLI
		192	+CLI CLI(Serial, banner); // Initialize the CLI, telling it to attach to Serial
		193	+Mode_Command Mode(CLI, BLINKING); // Initialize/Register mode command, BLINKING initially
		194	+Delay_Command Delay(CLI); // Initialize/Register delay command
		195	+Faster_Command Faster(CLI, Delay); // Initialize/Register faster command
		196	+Slower_Command Slower(CLI, Delay); // Initialize/Register slower command
		197	+Help_Command Help(CLI); // Initialize/Register (built-in) help command
		198	+
		199	+
		200	+// the setup function runs once when you reset or power the board
		201	+void setup() {
		202	+ // initialize digital pin LED_BUILTIN as an output.
		203	+ pinMode(LED_BUILTIN, OUTPUT);
		204	+
		205	+ // Initialize the Serial port for the CLI
		206	+ while (!Serial); // For Leonardo: wait for serial USB to connect
		207	+ Serial.begin(9600);
		208	+}
		209	+
		210	+// variable to be preserved
		211	+unsigned long last_blink = 0;
		212	+
		213	+// the loop function runs over and over again forever
		214	+void loop() {
		215	+ // First handle CLI, if this returns true, a command is running and the code
		216	+ // block with blink logic is skipped till the command has finished executing
		217	+ if (!CLI.process()) {
		218	+ // check if mode is blinking and last_blink was longer ago than delay
		219	+ // millis() will wrap every 49 days, below approach is wrap-proof
		220	+ if (Mode.get() == BLINKING && millis() - last_blink > Delay.get()) {
		221	+ last_blink = millis(); // led state will change, store when
		222	+ digitalWrite(LED_BUILTIN, !digitalRead(LED_BUILTIN)); // invert LED PIN
		223	+ }
		224	+ }
		225	+}
		226	+

examples/DS1307RTC/DS1307RTC.ino 0 → 100644

View file @47b5f8d

		1	+++ a/examples/DS1307RTC/DS1307RTC.ino
		1	+/*
		2	+ DS1307RTC.ino - CLI library sample implementing a CLI to control a DS1307 RTC
		3	+
		4	+ Version 1.0, latest version, documentation and bugtracker available at:
		5	+ https://gitlab.lindenaar.net/arduino/CLI
		6	+
		7	+ Copyright (c) 2019 Frederik Lindenaar
		8	+
		9	+ This example shows how to add commands to read and set an DS1307 RTC (Real
		10	+ Time Clock) module to the CLI. It extends the Debug example so that the CLI
		11	+ library debugging commands are also included to check the I2C bus wiring and
		12	+ access the module's NVRAM and EEPROM. The implementation uses Paul
		13	+ Stoffregen's DS1307RTC library (https://github.com/PaulStoffregen/DS1307RTC)
		14	+ so please ensure you have added that (and it's dependency TimeLib) through
		15	+ the Aruino IDE's built-in library manager.
		16	+
		17	+ The following commands are available through the Serial Monitor (available
		18	+ from the Tools menu of the Arduino IDE):
		19	+ - ds1307 Set and/or show DS1307 RTC date and time
		20	+ - eeprom_dump dump the contents of the built-in EEPROM
		21	+ - i2c_scan scan the I2C bus for slave devices
		22	+ - i2c_dump dump the contents of I2C attached EEPROM or Memory
		23	+ - reset restart the microcontroller (software reset)
		24	+ - help show the available commands and how to use them
		25	+
		26	+ To read the the DS1307 use:
		27	+ ds1307 show the current time of the DS1307
		28	+ i2c_dump 0x68 64 8 single show NVRAM (assuming device ID is 0x68)
		29	+ (dump 56-byte NVRAM, start at offset 8)
		30	+
		31	+ To set the DS1307 clock use:
		32	+ ds1307 2019-01-01 12:34:56 to set both the date and time
		33	+ ds1307 2019-01-31 to set only the date
		34	+ ds1307 12:34 to set only the time (seconds set to 0)
		35	+
		36	+ When your module also has an EEPROM (assuming device ID is 0x50) use:
		37	+ i2c_dump 0x50 4096 dump 24LC32 EEPROM contents (4k)
		38	+
		39	+ Please note that the ds1307 command is implemented in separate files (that
		40	+ opens in a separate tab in the Arduino IDE)
		41	+
		42	+ This sketch is free software: you can redistribute it and/or modify it under
		43	+ the terms of version 3 of the GNU General Public License as published by the
		44	+ Free Software Foundation, or (at your option) a later version of the license.
		45	+
		46	+ This code is distributed in the hope that it will be useful but WITHOUT ANY
		47	+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
		48	+ A PARTICULAR PURPOSE. See the GNU General Public License for more details.
		49	+
		50	+ You should have received a copy of the GNU General Public License along with
		51	+ this program. If not, visit <http://www.gnu.org/licenses/> to download it.
		52	+*/
		53	+
		54	+#include <CLI.h>
		55	+#include <Wire.h>
		56	+
		57	+#include "DS1307_Command.h"
		58	+
		59	+// Initialize the Debug Command Line Interface
		60	+const char banner[] PROGMEM = "DS1307RTC Sample CLI"; // Banner to show upon startup of the CLI
		61	+CLI CLI(Serial, banner); // Initialize the CLI, telling it to attach to Serial
		62	+DS1307_Command DS1307RTC(CLI); // Initialize/Register ds1307 command
		63	+EEPROM_Dump_Command EEPROM_Dump(CLI); // Initialize/Register (built-in) eeprom_dump command
		64	+I2C_Scan_Command I2C_Scan(CLI); // Initialize/Register (built-in) i2c_scan command
		65	+I2C_Dump_Command I2C_Dump(CLI); // Initialize/Register (built-in) i2c_dump command
		66	+Reset_Command Reset(CLI); // Initialize/Register (built-in) reset command
		67	+Help_Command Help(CLI); // Initialize/Register (built-in) help command
		68	+
		69	+
		70	+// the setup function runs once when you reset or power the board
		71	+void setup() {
		72	+ // initialize digital pin LED_BUILTIN as an output.
		73	+ pinMode(LED_BUILTIN, OUTPUT);
		74	+
		75	+ // Initialize the Serial port for the CLI
		76	+ while (!Serial); // For Leonardo: wait for serial USB to connect
		77	+ Serial.begin(9600);
		78	+
		79	+ // Initialize the Wire Interface
		80	+ Wire.begin();
		81	+
		82	+}
		83	+
		84	+
		85	+// the loop function runs over and over again forever
		86	+void loop() {
		87	+ // handle CLI, if this returns true a command is running. Set Builtin LED accordingly
		88	+ if (CLI.process()) {
		89	+ digitalWrite(LED_BUILTIN, HIGH); // turn LED on when processing CLI command
		90	+ } else {
		91	+ digitalWrite(LED_BUILTIN, LOW); // turn LED off when not processing CLI command
		92	+ }
		93	+}
		94	+

examples/DS1307RTC/DS1307_Command.cpp 0 → 100644

View file @47b5f8d

		1	+++ a/examples/DS1307RTC/DS1307_Command.cpp
		1	+/*
		2	+ DS1307_Command.cpp - CLI library for Arduino/ESP8266 - DS1307 Command implementation
		3	+
		4	+ Version 1.0, latest version, documentation and bugtracker available at:
		5	+ https://gitlab.lindenaar.net/arduino/CLI
		6	+
		7	+ Copyright (c) 2019 Frederik Lindenaar
		8	+
		9	+ This library is free software: you can redistribute it and/or modify it under
		10	+ the terms of version 3 of the GNU General Public License as published by the
		11	+ Free Software Foundation, or (at your option) a later version of the license.
		12	+
		13	+ This code is distributed in the hope that it will be useful but WITHOUT ANY
		14	+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
		15	+ A PARTICULAR PURPOSE. See the GNU General Public License for more details.
		16	+
		17	+ You should have received a copy of the GNU General Public License along with
		18	+ this program. If not, visit <http://www.gnu.org/licenses/> to download it.
		19	+*/
		20	+
		21	+#include <TimeLib.h>
		22	+#include <DS1307RTC.h>
		23	+
		24	+#include "DS1307_Command.h"
		25	+
		26	+DS1307_Command::DS1307_Command(CLI &cli) : // Constructor for ds1307 command
		27	+ CLI_Command(cli, // CLI to register with
		28	+ PSTR("ds1307"), // Command name
		29	+ PSTR("Set and/or show DS1307 RTC date and time"), // Description
		30	+ PSTR("Usage:\tds1307 [YYYY-MM-DD] [HH:MM[:SS]]\n" // Usage Help
		31	+ "where YYYY-MM-DD is the date in ISO format\n"
		32	+ " and HH:MM[:SS] the new time (seconds are optional)\n")) { };
		33	+
		34	+// macro to determine whether the given year is a leap year
		35	+#define LEAP_YEAR(y) (!((y) % 4) && (((y) % 100 ) \|\| !((y) % 400) ))
		36	+
		37	+inline uint8_t monthDays(int y, uint8_t m) { // get number of days for month
		38	+ return (m == 2) ? 28 + LEAP_YEAR(y) : 30 + ((m & 1) == (m <= 7));
		39	+}
		40	+
		41	+
		42	+// Function below parses the string passed in params (if provided) and sets the
		43	+// time accordingly. returns false in case an invalid date/time was found (and
		44	+// an invalid parameter message will be given) and true in case of no params or
		45	+// when a string of the format: [YYYY-MM-DD] [HH:MM[:SS]] is found. In case a
		46	+// partial date/time is provided, the remaining part will be substituted with
		47	+// the DS1307's current value. Additional whitespaces are ignored and values are
		48	+// checked for validity.
		49	+bool DS1307_Command::setparams(const char *params) {
		50	+ if (!params) return true; // return true when no parameter
		51	+ int value;
		52	+ tmElements_t tm;
		53	+ if (const char *sep = CLI_STR_parseInt(params, value)) { // parse first integer value
		54	+ RTC.read(tm); // Got a valid start get current time
		55	+ // check if character following the integer is a '-' and we have a valid year
		56	+ if (*sep == '-' && value >= tmYearToCalendar(0) && value <= tmYearToCalendar(255)) {
		57	+ // Got a valid year and date separator, parse the rest of the date
		58	+ tm.Year = CalendarYrToTm(value);
		59	+ if ((sep = CLI_STR_parseInt(sep + 1, value)) && value >= 1 && value <= 12 && *sep == '-') {
		60	+ tm.Month = value;
		61	+ if ((sep = CLI_STR_parseInt(sep + 1, value)) && value >= 1 &&
		62	+ value <= monthDays(tmYearToCalendar(tm.Year), value)) {
		63	+ tm.Day = value;
		64	+ sep = CLI_STR_skipSep(sep);
		65	+ if (*sep) sep = CLI_STR_parseInt(sep, value); // parse the hour integer
		66	+ } else return false; // exit if parsing a date and day is invald
		67	+ } else return false; // exit if parsing a date and month is invald
		68	+ }
		69	+ // check if character following the integer is a ':' and we have a valid hour
		70	+ if (*sep == ':' && value >= 0 && value < 24) {
		71	+ // Got a valid hour and time separator, parse the rest of the time
		72	+ tm.Hour = value;
		73	+ if ((sep = CLI_STR_parseInt(sep + 1, value)) && value >= 0 && value <= 59) {
		74	+ tm.Minute = value;
		75	+ if (*sep == ':') { // if next char is a separator, parse seconds
		76	+ if ((sep = CLI_STR_parseInt(sep + 1, value)) && value >= 0 && value <= 59) {
		77	+ tm.Second = value;
		78	+ } else return false;
		79	+ } else tm.Second = 0; // otherwise set seconds to 0
		80	+ } else return false; // exit if minutes is invalid
		81	+ }
		82	+ if (*CLI_STR_skipSep(sep)) return false; // if not the end of the string, return false
		83	+ RTC.write(tm); // if we get here, we have a valid time in tm, set it
		84	+ return true; // return true as we got valid input
		85	+ }
		86	+ return false; // no valid parameter, return false
		87	+}
		88	+
		89	+bool DS1307_Command::execute(CLI &cli) { // execute prints the current time
		90	+ tmElements_t tm;
		91	+ if (RTC.read(tm)) { // get current time from DS1307
		92	+ cli.print(dayStr(tm.Wday)); // print day of week
		93	+ cli.print(' ');
		94	+ cli.print(tm.Day); // print day of month
		95	+ cli.print(' ');
		96	+ cli.print(monthStr(tm.Month)); // print month name
		97	+ cli.print(' ');
		98	+ cli.print(tmYearToCalendar(tm.Year)); // print year
		99	+ cli.print(' ');
		100	+ cli.print2digits(tm.Hour); // print hour
		101	+ cli.print(':');
		102	+ cli.print2digits(tm.Minute); // print minute
		103	+ cli.print(':');
		104	+ cli.print2digits(tm.Second); // print seconds
		105	+ } else { // if get time fails, print an error
		106	+ if (RTC.chipPresent()) { // if a chip was found, it is not set
		107	+ cli.print_P(PSTR("Error: cannot read RTC clock, please set time\n"));
		108	+ } else { // otherwise tell user no DS1307 was found
		109	+ cli.print_P(PSTR("Error: RTC clock not found, check wiring\n"));
		110	+ }
		111	+ }
		112	+ return false; // We're done and should not be called again
		113	+}
		114	+

examples/DS1307RTC/DS1307_Command.h 0 → 100644

View file @47b5f8d

		1	+++ a/examples/DS1307RTC/DS1307_Command.h
		1	+/*
		2	+ DS1307_Command.cpp - CLI library for Arduino/ESP8266 - DS1307 Command definitions
		3	+
		4	+ Version 1.0, latest version, documentation and bugtracker available at:
		5	+ https://gitlab.lindenaar.net/arduino/CLI
		6	+
		7	+ Copyright (c) 2019 Frederik Lindenaar
		8	+
		9	+ This library is free software: you can redistribute it and/or modify it under
		10	+ the terms of version 3 of the GNU General Public License as published by the
		11	+ Free Software Foundation, or (at your option) a later version of the license.
		12	+
		13	+ This code is distributed in the hope that it will be useful but WITHOUT ANY
		14	+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
		15	+ A PARTICULAR PURPOSE. See the GNU General Public License for more details.
		16	+
		17	+ You should have received a copy of the GNU General Public License along with
		18	+ this program. If not, visit <http://www.gnu.org/licenses/> to download it.
		19	+*/
		20	+
		21	+#include <CLI.h>
		22	+
		23	+class DS1307_Command : public CLI_Command { // Definition of ds1307 command
		24	+ public:
		25	+ DS1307_Command(CLI &cli); // Constructor, requires CLI
		26	+ bool setparams(const char *params); // Parameter parser
		27	+ bool execute(CLI &cli); // Implementation of logic
		28	+};
		29	+

examples/Debug/Debug.ino 0 → 100644

View file @47b5f8d

		1	+++ a/examples/Debug/Debug.ino
		1	+/*
		2	+ Debug.ino - CLI library sample implementing a CLI for the Blink sample code
		3	+
		4	+ Version 1.0, latest version, documentation and bugtracker available at:
		5	+ https://gitlab.lindenaar.net/arduino/CLI
		6	+
		7	+ Copyright (c) 2019 Frederik Lindenaar
		8	+
		9	+ This sketch demonstrates the debugging commands available as part of the CLI
		10	+ library. These commands are intended to eliminate the need to write code to
		11	+ check things in or connected to your microcontroller. Over time, additional
		12	+ commands will be added, when needed (feel free to submit your favorites for
		13	+ inclusion!). At this moment it makes the following commands available through
		14	+ the Serial Monitor (available from the Tools menu of the Arduino IDE):
		15	+ - eeprom_dump dump the contents of the built-in EEPROM
		16	+ - i2c_scan scan the I2C bus for slave devices
		17	+ - i2c_dump dump the contents of I2C attached EEPROM or Memory
		18	+ - reset restart the microcontroller (software reset)
		19	+ - help show the available commands and how to use them
		20	+
		21	+ For each of these commands the implementation is included in the CLI library.
		22	+
		23	+ This sketch is free software: you can redistribute it and/or modify it under
		24	+ the terms of version 3 of the GNU General Public License as published by the
		25	+ Free Software Foundation, or (at your option) a later version of the license.
		26	+
		27	+ This code is distributed in the hope that it will be useful but WITHOUT ANY
		28	+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
		29	+ A PARTICULAR PURPOSE. See the GNU General Public License for more details.
		30	+
		31	+ You should have received a copy of the GNU General Public License along with
		32	+ this program. If not, visit <http://www.gnu.org/licenses/> to download it.
		33	+*/
		34	+
		35	+#include <CLI.h>
		36	+#include <Wire.h>
		37	+
		38	+// Initialize the Debug Command Line Interface
		39	+const char banner[] PROGMEM = "Debug Sample CLI"; // Banner to show upon startup of the CLI
		40	+CLI CLI(Serial, banner); // Initialize the CLI, telling it to attach to Serial
		41	+EEPROM_Dump_Command EEPROM_Dump(CLI); // Initialize/Register (built-in) eeprom_dump command
		42	+I2C_Scan_Command I2C_Scan(CLI); // Initialize/Register (built-in) i2c_scan command
		43	+I2C_Dump_Command I2C_Dump(CLI); // Initialize/Register (built-in) i2c_dump command
		44	+Reset_Command Reset(CLI); // Initialize/Register (built-in) reset command
		45	+Help_Command Help(CLI); // Initialize/Register (built-in) help command
		46	+
		47	+
		48	+// the setup function runs once when you reset or power the board
		49	+void setup() {
		50	+ // initialize digital pin LED_BUILTIN as an output.
		51	+ pinMode(LED_BUILTIN, OUTPUT);
		52	+
		53	+ // Initialize the Serial port for the CLI
		54	+ while (!Serial); // For Leonardo: wait for serial USB to connect
		55	+ Serial.begin(9600);
		56	+
		57	+ // Initialize the Wire Interface
		58	+ Wire.begin();
		59	+}
		60	+
		61	+
		62	+// the loop function runs over and over again forever
		63	+void loop() {
		64	+ // handle CLI, if this returns true a command is running. Set Builtin LED accordingly
		65	+ if (CLI.process()) {
		66	+ digitalWrite(LED_BUILTIN, HIGH); // turn LED on when processing CLI command
		67	+ } else {
		68	+ digitalWrite(LED_BUILTIN, LOW); // turn LED off when not processing CLI command
		69	+ }
		70	+}
		71	+

keywords.txt 0 → 100644

View file @47b5f8d

		1	+++ a/keywords.txt
		1	+#######################################
		2	+# Syntax Coloring Map for CLI v1.0
		3	+#######################################
		4	+
		5	+#######################################
		6	+# Datatypes (KEYWORD1)
		7	+#######################################
		8	+CLI KEYWORD1
		9	+CLI_Command KEYWORD1
		10	+
		11	+CLI_State KEYWORD1
		12	+CLI_Command_Param KEYWORD1
		13	+CLI_Command_Flags KEYWORD1
		14	+
		15	+Help_Command KEYWORD1
		16	+Reset_Command KEYWORD1
		17	+EEPROM_Dump_Command KEYWORD1
		18	+I2C_Scan_Command KEYWORD1
		19	+I2C_Dump_Command KEYWORD1
		20	+
		21	+#######################################
		22	+# Methods and Functions (KEYWORD2)
		23	+#######################################
		24	+
		25	+# functions
		26	+CLI_STR_skipSep KEYWORD2
		27	+CLI_STR_findSep KEYWORD2
		28	+CLI_STR_parseInt KEYWORD2
		29	+CLI_STR_parseParam_P KEYWORD2
		30	+CLI_STR_parseFlags_P KEYWORD2
		31	+
		32	+# CLI
		33	+process KEYWORD2
		34	+add_command KEYWORD2
		35	+get_command KEYWORD2
		36	+find_command KEYWORD2
		37	+command_count KEYWORD2
		38	+print_P KEYWORD2
		39	+print2digits KEYWORD2
		40	+print_mem KEYWORD2
		41	+printtab KEYWORD2
		42	+
		43	+# CLI_Command
		44	+matches KEYWORD2
		45	+setparams KEYWORD2
		46	+execute KEYWORD2
		47	+
		48	+#######################################
		49	+# Constants (LITERAL1)
		50	+#######################################
		51	+CLI_MAX_CMDS LITERAL1
		52	+CLI_MAX_LINE LITERAL1
		53	+
		54	+STATE_INIT LITERAL1
		55	+STATE_READY LITERAL1
		56	+STATE_INPUT LITERAL1
		57	+STATE_PARSE LITERAL1
		58	+STATE_EXEC LITERAL1
		59	+

library.json 0 → 100644

View file @47b5f8d

		1	+++ a/library.json
		1	+{
		2	+ "name": "CLI",
		3	+ "description": "Library to buid a real-time serial (or network) command-line interface (CLI) to configure or control your microcontroller.",
		4	+ "keywords": "CLI, Commandline",
		5	+ "homepage": "https://gitlab.lindenaar.net/arduino/CLI",
		6	+ "authors": {
		7	+ "name": "Frederik Lindenaar",
		8	+ "url": "https://frederik.lindenaar.nl",
		9	+ "maintainer": true
		10	+ },
		11	+ "repository": {
		12	+ "type": "git",
		13	+ "url": "https://gitlab.lindenaar.net/arduino/CLI.git"
		14	+ },
		15	+ "version": "1.0",
		16	+ "license": "GPL",
		17	+ "frameworks": [ "arduino" ],
		18	+ "platforms": "*",
		19	+ "examples": "examples//.ino"
		20	+}
		21	+

library.properties 0 → 100644

View file @47b5f8d

		1	+++ a/library.properties
		1	+name=Command Line Interface
		2	+version=1.0
		3	+author=Frederik Lindenaar
		4	+maintainer=Frederik Lindenaar
		5	+sentence=Library to build a Command Line Interface (CLI)
		6	+paragraph=Library to bui;d a real-time serial (or network) command-line interface (CLI) to configure or control your microcontroller.
		7	+category=Device Control
		8	+url=https://gitlab.lindenaar.net/arduino/CLI
		9	+architectures=*
		10	+license=GPL
		11	+includes=CLI.h
		12	+

src/CLI.cpp 0 → 100644

View file @47b5f8d

		1	+++ a/src/CLI.cpp
		1	+/*
		2	+ * CLI.cpp - CLI library for Arduino/ESP8266 and others implementation
		3	+ *
		4	+ * Version 1.0, latest version, documentation and bugtracker available at:
		5	+ * https://gitlab.lindenaar.net/arduino/CLI
		6	+ *
		7	+ * Copyright (c) 2019 Frederik Lindenaar
		8	+ *
		9	+ * This library is free software: you can redistribute it and/or modify it under
		10	+ * the terms of version 3 of the GNU General Public License as published by the
		11	+ * Free Software Foundation, or (at your option) a later version of the license.
		12	+ *
		13	+ * This code is distributed in the hope that it will be useful but WITHOUT ANY
		14	+ * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
		15	+ * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
		16	+ *
		17	+ * You should have received a copy of the GNU General Public License along with
		18	+ * this program. If not, visit <http://www.gnu.org/licenses/> to download it.
		19	+ */
		20	+
		21	+#include <CLI.h>
		22	+
		23	+#define CHAR_TAB '\t'
		24	+#define CHAR_BS '\b'
		25	+#define CHAR_DELETE char(127)
		26	+#define CHAR_CR '\r'
		27	+#define CHAR_LF '\n'
		28	+
		29	+const char CLI_DEFAULT_PROMPT[] PROGMEM = "\n> ";
		30	+const char CLI_PREFIX_PARAMETER_ERROR[] PROGMEM = "Invalid parameters for ";
		31	+const char CLI_PREFIX_UNKNOWN_COMMAND[] PROGMEM = "Unknown command ";
		32	+
		33	+size_t CLI::print_P (const char *str PROGMEM) {
		34	+ size_t len = 0;
		35	+ if (str) {
		36	+ while (char c = pgm_read_byte(str++)) {
		37	+ write(c);
		38	+ len++;
		39	+ }
		40	+ }
		41	+ return len;
		42	+}
		43	+
		44	+void CLI::print2digits(uint8_t num, char filler, uint8_t base) {
		45	+ if (num < base) print(filler);
		46	+ print(num, base);
		47	+}
		48	+
		49	+void CLI::print_mem(uint16_t addr, const uint8_t buff[], uint8_t len, uint8_t width) {
		50	+ if (addr < 0x1000) print(' ');
		51	+ if (addr < 0x100) print(' ');
		52	+ if (addr < 0x10) print(' ');
		53	+ print(addr, HEX);
		54	+ print(':');
		55	+
		56	+ for (uint8_t i = 0; i < len; i++) {
		57	+ print(' ');
		58	+ if (buff[i] < 0x10) print(0);
		59	+ print(buff[i], HEX);
		60	+ }
		61	+ while (width > len++) print_P(PSTR(" "));
		62	+
		63	+ print('\t');
		64	+ for (uint8_t i = 0; i < len; i++)
		65	+ write(isprint(buff[i]) ? buff[i] : '.');
		66	+
		67	+ println();
		68	+}
		69	+
		70	+void CLI::printtab() {
		71	+ print(CHAR_TAB);
		72	+};
		73	+
		74	+CLI::CLI(Stream &stream, const char banner PROGMEM, const char prompt PROGMEM) : _stream(&stream), _banner(banner) {
		75	+ _state = STATE_INIT;
		76	+ _command_count = 0;
		77	+ _prompt = (prompt) ? prompt : CLI_DEFAULT_PROMPT;
		78	+};
		79	+
		80	+void CLI::add_command(CLI_Command *cmd) {
		81	+ if (_command_count < CLI_MAX_CMDS)
		82	+ _commands[_command_count++] = cmd;
		83	+};
		84	+
		85	+CLI_Command *CLI::get_command(int index) {
		86	+ return (index < _command_count) ? _commands[index] : NULL;
		87	+}
		88	+
		89	+CLI_Command CLI::get_command(const char name, int namelen) {
		90	+ for (int i = 0; i < _command_count; i++) {
		91	+ if (_commands[i]->matches(name, namelen)) return _commands[i];
		92	+ }
		93	+ return NULL;
		94	+}
		95	+
		96	+#if CLI_MAX_CMDS < 255
		97	+uint8_t CLI::find_command(const char *name, int namelen) {
		98	+ uint8_t idx = _command_count;
		99	+#else
		100	+uint16_t CLI::find_command(const char *name, int namelen) {
		101	+ uint16_t idx = _command_count;
		102	+#endif
		103	+ while (idx-- && !_commands[idx]->matches(name, namelen));
		104	+ return idx;
		105	+}
		106	+
		107	+bool CLI::process() { // Workhorse of the CLI
		108	+ if (_state == STATE_INIT) { // INIT: print banner (if set)
		109	+ if (_banner) {
		110	+ print_P(_banner);
		111	+ println();
		112	+ }
		113	+ _state = STATE_READY;
		114	+ } else if (_state == STATE_READY) { // READY: print prompt & init
		115	+ print_P(_prompt);
		116	+ memset(_cmdbuffer, 0, _line_len);
		117	+ _line_len = 0;
		118	+ _current_cmd = NULL;
		119	+ _state = STATE_INPUT;
		120	+ } else if (_state == STATE_INPUT) { // INPUT: process user input
		121	+ while (available()) { // loop while stream input
		122	+ int c = read(); // get next char
		123	+ if (c == CHAR_DELETE) { // Process BACKSPACE key
		124	+ print_P(PSTR("\b \b"));
		125	+ if (_line_len) _cmdbuffer[_line_len--] = 0;
		126	+ } else if (c == CHAR_CR) { // Process ENTER key
		127	+ println();
		128	+ _state = STATE_PARSE; // Change state to PARSE
		129	+ return false; // and stop processing input
		130	+ } else if (c != CHAR_LF && isprint(c)) { // Process other valid input
		131	+ if (_line_len < CLI_MAX_LINE - 1) { // add to line if space left
		132	+ _cmdbuffer[_line_len++] = c;
		133	+ write(c); // print char to echo input
		134	+ } else { // if not, beep & ignore
		135	+ write(char(7));
		136	+ }
		137	+ }
		138	+ }
		139	+ } else if (_state == STATE_PARSE) { // PARSE: parse user command
		140	+ const char *cmd = CLI_STR_skipSep(_cmdbuffer); // skip initial whitespace
		141	+ if (*cmd && cmd - _cmdbuffer < _line_len) { // do we have a command?
		142	+ for (char p = _cmdbuffer + _line_len - 1; p == ' '; p--, _line_len--)
		143	+ *p = 0; // clear trailing whitespace
		144	+ const char *sep = CLI_STR_findSep(cmd); // find end of command
		145	+ if (_current_cmd = get_command(cmd, sep - cmd)) { // known command?
		146	+ sep = CLI_STR_skipSep(sep); // get start of params
		147	+ if (_current_cmd->setparams((*sep) ? sep : 0)) {// parse params
		148	+ _state = STATE_EXEC; // all OK, change state
		149	+ return true; // and stop processing
		150	+ } else print_P(CLI_PREFIX_PARAMETER_ERROR); // print invalid parameters
		151	+ } else print_P(CLI_PREFIX_UNKNOWN_COMMAND) ; // print unknown command
		152	+ _stream->write(cmd, sep - cmd); // print command name
		153	+ println(); // and add newline
		154	+ }
		155	+ _state = STATE_READY; // if we get here: READY
		156	+ } else if (_state == STATE_EXEC) { // EXEC: execute the command
		157	+ if (_current_cmd->execute(*this)) { // Execute, false when done
		158	+ return true; // not yet done, return true
		159	+ } else {
		160	+ _state = STATE_READY; // done, READY
		161	+ }
		162	+ }
		163	+ return false; // default result false (done)
		164	+}
		165	+
		166	+
		167	+CLI_Command::CLI_Command(CLI &cli, const char command, const char description, const char *usagehelp) : command(command), description(description), usagehelp(usagehelp) {
		168	+ cli.add_command(this);
		169	+};
		170	+
		171	+bool CLI_Command::matches(const char *cmd, uint8_t cmdlen) {
		172	+ return pgm_read_byte(&command[cmdlen]) == 0 && strncmp_P(cmd, command, cmdlen) == 0;
		173	+};
		174	+
		175	+bool CLI_Command::setparams(const char *params) {
		176	+ return !params;
		177	+}
		178	+

src/CLI.h 0 → 100644

View file @47b5f8d

		1	+++ a/src/CLI.h
		1	+/*
		2	+ * CLI.h - CLI library for Arduino/ESP8266 and others definitions
		3	+ *
		4	+ * Version 1.0, latest version, documentation and bugtracker available at:
		5	+ * https://gitlab.lindenaar.net/arduino/CLI
		6	+ *
		7	+ * Copyright (c) 2019 Frederik Lindenaar
		8	+ *
		9	+ * This library is free software: you can redistribute it and/or modify it under
		10	+ * the terms of version 3 of the GNU General Public License as published by the
		11	+ * Free Software Foundation, or (at your option) a later version of the license.
		12	+ *
		13	+ * This code is distributed in the hope that it will be useful but WITHOUT ANY
		14	+ * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
		15	+ * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
		16	+ *
		17	+ * You should have received a copy of the GNU General Public License along with
		18	+ * this program. If not, visit <http://www.gnu.org/licenses/> to download it.
		19	+ */
		20	+
		21	+#include <Stream.h>
		22	+
		23	+#ifndef CLI_H
		24	+#define CLI_H
		25	+
		26	+#ifndef CLI_MAX_CMDS
		27	+ #define CLI_MAX_CMDS 16
		28	+#endif // CLI_MAX_CMDS
		29	+
		30	+#ifndef CLI_MAX_LINE
		31	+ #define CLI_MAX_LINE 80
		32	+#endif // CLI_MAX_LINE
		33	+
		34	+class CLI;
		35	+
		36	+struct CLI_Command_Param {
		37	+ const char *param PROGMEM;
		38	+ union {
		39	+ int int16;
		40	+ uint16_t uint16;
		41	+ int8_t int8;
		42	+ uint8_t uint8;
		43	+ int32_t int32;
		44	+ uint32_t uint32;
		45	+ char *str PROGMEM;
		46	+ };
		47	+};
		48	+
		49	+struct CLI_Command_Flags {
		50	+ const char *command;
		51	+ uint8_t cmdlen, flags, intparam;
		52	+};
		53	+
		54	+const char CLI_STR_skipSep(const char str);
		55	+const char CLI_STR_findSep(const char str);
		56	+const char CLI_STR_parseInt(const char , int &, int = -32768, int = 32767);
		57	+const char CLI_STR_parse_HEX_byte(const char , uint8_t &);
		58	+const struct CLI_Command_Param CLI_STR_parseParam_P (const char , const struct CLI_Command_Param params[]);
		59	+const char CLI_STR_parseFlags_P (const char , const struct CLI_Command_Flags params[], uint8_t, uint8_t, uint8_t *);
		60	+
		61	+class CLI_Command {
		62	+ friend class Help_Command;
		63	+ friend class CLI;
		64	+ protected:
		65	+ const char command, description, *usagehelp;
		66	+ bool matches(const char *cmd, uint8_t cmdlen);
		67	+ public:
		68	+ CLI_Command(CLI &cli , const char command PROGMEM, const char description PROGMEM, const char *help PROGMEM = NULL);
		69	+ virtual bool setparams(const char *params);
		70	+ virtual bool execute(CLI &cli) = 0;
		71	+};
		72	+
		73	+
		74	+class Help_Command : public CLI_Command {
		75	+ CLI &_cli;
		76	+#if CLI_MAX_CMDS < 255
		77	+ uint8_t _cmd_idx;
		78	+#else
		79	+ uint16_t _cmd_idx;
		80	+#endif
		81	+ bool _cmd_list;
		82	+ public:
		83	+ Help_Command(CLI &cli);
		84	+ bool setparams(const char *);
		85	+ bool execute(CLI &cli);
		86	+};
		87	+
		88	+
		89	+class EEPROM_Dump_Command : public CLI_Command {
		90	+ int _offset;
		91	+ public:
		92	+ EEPROM_Dump_Command(CLI &cli);
		93	+ bool setparams(const char *);
		94	+ bool execute(CLI &cli);
		95	+};
		96	+
		97	+class Reset_Command : public CLI_Command {
		98	+ int _resetting;
		99	+ public:
		100	+ Reset_Command(CLI &cli);
		101	+ bool execute(CLI &cli);
		102	+};
		103	+
		104	+class I2C_Scan_Command : public CLI_Command {
		105	+ uint8_t _address, _found;
		106	+ public:
		107	+ I2C_Scan_Command(CLI &cli);
		108	+ bool setparams(const char *);
		109	+ bool execute(CLI &cli);
		110	+};
		111	+
		112	+class I2C_Dump_Command : public CLI_Command {
		113	+ uint8_t _address;
		114	+ bool _large;
		115	+ uint16_t _length, _offset;
		116	+ public:
		117	+ I2C_Dump_Command(CLI &cli);
		118	+ bool setparams(const char *);
		119	+ bool execute(CLI &cli);
		120	+};
		121	+
		122	+
		123	+class CLI : public Stream {
		124	+ enum CLI_State { STATE_INIT, STATE_READY, STATE_INPUT, STATE_PARSE, STATE_EXEC } _state;
		125	+#if CLI_MAX_CMDS < 255
		126	+ uint8_t _command_count;
		127	+#else
		128	+ uint16_t _command_count;
		129	+#endif
		130	+ CLI_Command *_commands[CLI_MAX_CMDS];
		131	+#if CLI_MAX_LINE < 255
		132	+ uint8_t _line_len;
		133	+#else
		134	+ uint16_t _line_len;
		135	+#endif
		136	+ char _cmdbuffer[CLI_MAX_LINE];
		137	+ // const char *_params;
		138	+ CLI_Command *_current_cmd;
		139	+ protected:
		140	+ Stream *_stream;
		141	+ const char _banner, _prompt;
		142	+ public:
		143	+ CLI(Stream &stream, const char banner PROGMEM = NULL, const char prompt PROGMEM = NULL);
		144	+ void add_command(CLI_Command *cmd);
		145	+ CLI_Command *get_command(int);
		146	+ CLI_Command get_command(const char , int);
		147	+#if CLI_MAX_CMDS < 256
		148	+ uint8_t find_command(const char *, int);
		149	+ inline uint8_t command_count() {
		150	+#else
		151	+ uint16_t find_command(const char *, int);
		152	+ inline uint16_t command_count() {
		153	+#endif
		154	+ return _command_count;
		155	+ };
		156	+
		157	+ inline int available() {
		158	+ return _stream->available();
		159	+ };
		160	+
		161	+ inline int peek() {
		162	+ return _stream->peek();
		163	+ };
		164	+
		165	+ inline int read() {
		166	+ return _stream->read();
		167	+ };
		168	+
		169	+ inline size_t write(uint8_t c) {
		170	+ return _stream->write(c);
		171	+ };
		172	+
		173	+ size_t print_P (const char *str PROGMEM);
		174	+ void print2digits(uint8_t num, char filler = '0', uint8_t base=10);
		175	+ void print_mem(uint16_t addr, const uint8_t buff[], uint8_t len, uint8_t width=16);
		176	+ void printtab();
		177	+
		178	+ bool process();
		179	+};
		180	+
		181	+#endif // CLI_H
		182	+

src/CLI_Utils.cpp 0 → 100644

View file @47b5f8d

		1	+++ a/src/CLI_Utils.cpp
		1	+/*
		2	+ * CLI_Utils.cpp - CLI library for Arduino/ESP8266 and others utility functions
		3	+ *
		4	+ * Version 1.0, latest version, documentation and bugtracker available at:
		5	+ * https://gitlab.lindenaar.net/arduino/CLI
		6	+ *
		7	+ * Copyright (c) 2019 Frederik Lindenaar
		8	+ *
		9	+ * This library is free software: you can redistribute it and/or modify it under
		10	+ * the terms of version 3 of the GNU General Public License as published by the
		11	+ * Free Software Foundation, or (at your option) a later version of the license.
		12	+ *
		13	+ * This code is distributed in the hope that it will be useful but WITHOUT ANY
		14	+ * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
		15	+ * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
		16	+ *
		17	+ * You should have received a copy of the GNU General Public License along with
		18	+ * this program. If not, visit <http://www.gnu.org/licenses/> to download it.
		19	+ */
		20	+
		21	+#include <CLI.h>
		22	+
		23	+const char CLI_STR_skipSep(const char str) {
		24	+ while (*str == ' ') str++;
		25	+ return str;
		26	+};
		27	+
		28	+const char CLI_STR_findSep(const char str) {
		29	+ while (str && str != ' ') str++;
		30	+ return str;
		31	+};
		32	+
		33	+const char CLI_STR_parseInt(const char str, int &value, int minvalue, int maxvalue) {
		34	+ int v = 0;
		35	+ const char *p = str;
		36	+ bool negative = *p == '-';
		37	+ if (negative \|\| *p == '+') p++;
		38	+ while (p >= '0' && p <= '9') {
		39	+ v *= 10;
		40	+ v += *(p++) - '0';
		41	+ }
		42	+ if (str != p && v >= minvalue && v <= maxvalue) {
		43	+ value = (negative) ? -v : v;
		44	+ return p;
		45	+ }
		46	+ return 0;
		47	+}
		48	+
		49	+uint8_t parseHexNibble(char c) {
		50	+ if(c >= 'a' && c <= 'f') {
		51	+ return c - 'a' + 10;
		52	+ } else if(c >= 'A' && c <= 'F') {
		53	+ return c - 'A' + 10;
		54	+ } else if(c >= '0' && c <= '9') {
		55	+ return c - '0';
		56	+ } else return 0xff;
		57	+}
		58	+
		59	+const char CLI_STR_parse_HEX_byte(const char str, uint8_t &value) {
		60	+ if (str) {
		61	+ uint8_t v;
		62	+ if((v = parseHexNibble(*(str++))) <= 0xf) {
		63	+ value = v << 4;
		64	+ if((v = parseHexNibble(*(str++))) <= 0xf) {
		65	+ value \|= v;
		66	+ return str;
		67	+ }
		68	+ }
		69	+ }
		70	+ return NULL;
		71	+}
		72	+
		73	+const struct CLI_Command_Param CLI_STR_parseParam_P (const char param, const struct CLI_Command_Param params[]) {
		74	+ for (const struct CLI_Command_Param *p = params; pgm_read_ptr(&p->param); p++)
		75	+ if (!strcmp_P(param, (char *)pgm_read_ptr(&p->param))) return p;
		76	+ return NULL;
		77	+}
		78	+
		79	+const char CLI_STR_parseFlags_P (const char str, const struct CLI_Command_Flags params[], uint8_t param_count, uint8_t mask, uint8_t *flags) {
		80	+ uint8_t f = 0;
		81	+ while (*str) {
		82	+ const struct CLI_Command_Flags *p = params;
		83	+ while (p <= &params[param_count] && strncmp_P(str, pgm_read_word(&p->command), pgm_read_byte(&p->cmdlen)) ) p++;
		84	+ uint8_t flags = pgm_read_byte(&p->flags);
		85	+ if (p > &params[param_count] \|\| (f != 0 && ((f & mask) != (flags & mask)))) return 0;
		86	+ f \|= flags;
		87	+ str = CLI_STR_skipSep(str + pgm_read_byte(&p->cmdlen));
		88	+
		89	+ if (uint8_t intparam = pgm_read_byte(&p->intparam)) {
		90	+ int i;
		91	+ if (str = CLI_STR_parseInt(str, i)) {
		92	+ if (pgm_read_byte(&p->cmdlen) == 0)
		93	+ if (int divider = pgm_read_word(&p->command)) {
		94	+ i /= divider & 0xff;
		95	+ i += divider >> 8;
		96	+ }
		97	+ if (i <= (intparam & 0x1f)) {
		98	+ f \|= i << (intparam >> 5);
		99	+ str = CLI_STR_skipSep(str);
		100	+ continue;
		101	+ }
		102	+ }
		103	+ return 0;
		104	+ }
		105	+ }
		106	+ if (*str) return 0;
		107	+ *flags = f;
		108	+ return str;
		109	+}
		110	+

src/Commands.cpp 0 → 100644

View file @47b5f8d

		1	+++ a/src/Commands.cpp
		1	+/*
		2	+ * CLI_Commands.cpp - CLI library for Arduino/ESP8266 and others general commands
		3	+ *
		4	+ * Version 1.0, latest version, documentation and bugtracker available at:
		5	+ * https://gitlab.lindenaar.net/arduino/CLI
		6	+ *
		7	+ * Copyright (c) 2019 Frederik Lindenaar
		8	+ *
		9	+ * This library is free software: you can redistribute it and/or modify it under
		10	+ * the terms of version 3 of the GNU General Public License as published by the
		11	+ * Free Software Foundation, or (at your option) a later version of the license.
		12	+ *
		13	+ * This code is distributed in the hope that it will be useful but WITHOUT ANY
		14	+ * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
		15	+ * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
		16	+ *
		17	+ * You should have received a copy of the GNU General Public License along with
		18	+ * this program. If not, visit <http://www.gnu.org/licenses/> to download it.
		19	+ */
		20	+
		21	+#include <CLI.h>
		22	+#include <avr/eeprom.h>
		23	+
		24	+Help_Command::Help_Command(CLI & cli) :
		25	+ CLI_Command(cli, PSTR("help"), PSTR("Display command help"),
		26	+ PSTR("Usage: help [<command>]\n"
		27	+ "\tdisplays usage help for <command> or lists available commands\n"
		28	+ "\twhen called without parameters\n")), _cli(cli) { };
		29	+
		30	+bool Help_Command::setparams(const char *params) {
		31	+ if (_cmd_list = !params) {
		32	+ _cmd_idx = 0;
		33	+ return true;
		34	+ } else {
		35	+ _cmd_idx = _cli.find_command(params, strlen(params));
		36	+ return _cmd_idx < _cli.command_count();
		37	+ }
		38	+}
		39	+
		40	+bool Help_Command::execute(CLI &cli) {
		41	+ if(CLI_Command *cmd = cli.get_command(_cmd_idx)) {
		42	+ if (_cmd_list) {
		43	+ if (_cmd_idx == 0) cli.print_P(PSTR("Known Commands:\n"));
		44	+ _cmd_idx++;
		45	+ cli.printtab();
		46	+ if (cli.print_P(cmd->command) < 8) cli.printtab();
		47	+ cli.printtab();
		48	+ cli.print_P(cmd->description);
		49	+ cli.println();
		50	+ return true;
		51	+ } else {
		52	+ cli.print_P(cmd->description);
		53	+ cli.println();
		54	+ if (cmd->usagehelp) cli.print_P(cmd->usagehelp);
		55	+ }
		56	+ } else if (_cmd_list) {
		57	+ cli.print_P((_cmd_idx)
		58	+ ? PSTR("\nfor more information on a command use \"help <command>\"")
		59	+ : PSTR("No Commands"));
		60	+ }
		61	+ cli.println();
		62	+ return false;
		63	+}
		64	+
		65	+
		66	+EEPROM_Dump_Command::EEPROM_Dump_Command(CLI & cli) : CLI_Command(cli,
		67	+ PSTR("eeprom_dump"), PSTR("Show EEPROM contents in HEX and ASCII")) { };
		68	+
		69	+bool EEPROM_Dump_Command::setparams(const char *params) {
		70	+ _offset = 0;
		71	+ return !params && E2END > 0;
		72	+}
		73	+
		74	+bool EEPROM_Dump_Command::execute(CLI &cli) {
		75	+ if (_offset == 0) {
		76	+ cli.print_P(PSTR("EEPROM Size: "));
		77	+ cli.print(E2END + 1);
		78	+ cli.print_P(PSTR(" Bytes\n\n"));
		79	+ }
		80	+ uint8_t buffer[16];
		81	+ eeprom_read_block(&buffer, (void *)_offset, sizeof(buffer));
		82	+ cli.print_mem(_offset, buffer, sizeof(buffer));
		83	+ _offset += sizeof(buffer);
		84	+ return _offset <= E2END;
		85	+}
		86	+
		87	+
		88	+Reset_Command::Reset_Command(CLI & cli) : CLI_Command(cli,
		89	+ PSTR("reset"), PSTR("Restart microcontroller")) { };
		90	+
		91	+void(* resetFunc) (void) = 0; //declare reset function @ address 0
		92	+bool Reset_Command::execute(CLI &cli) {
		93	+ if (_resetting == 2000) resetFunc();
		94	+ if (!_resetting) cli.print(PSTR("resetting...\n\n"));
		95	+ _resetting++;
		96	+ return true;
		97	+}
		98	+

src/I2C_Commands.cpp 0 → 100644

View file @47b5f8d

		1	+++ a/src/I2C_Commands.cpp
		1	+/*
		2	+ * CLI_I2C_Commands.cpp - CLI library for Arduino/ESP8266 - I2C Commands implementation
		3	+ *
		4	+ * Version 1.0, latest version, documentation and bugtracker available at:
		5	+ * https://gitlab.lindenaar.net/arduino/CLI
		6	+ *
		7	+ * Copyright (c) 2019 Frederik Lindenaar
		8	+ *
		9	+ * This library is free software: you can redistribute it and/or modify it under
		10	+ * the terms of version 3 of the GNU General Public License as published by the
		11	+ * Free Software Foundation, or (at your option) a later version of the license.
		12	+ *
		13	+ * This code is distributed in the hope that it will be useful but WITHOUT ANY
		14	+ * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
		15	+ * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
		16	+ *
		17	+ * You should have received a copy of the GNU General Public License along with
		18	+ * this program. If not, visit <http://www.gnu.org/licenses/> to download it.
		19	+ */
		20	+
		21	+#include <CLI.h>
		22	+#include <Wire.h>
		23	+
		24	+I2C_Scan_Command::I2C_Scan_Command(CLI & cli) : CLI_Command(cli,
		25	+ PSTR("i2c_scan"), PSTR("Scan I2C bus for slave devices")) { };
		26	+
		27	+bool I2C_Scan_Command::setparams(const char *params) {
		28	+ _address = _found = 0;
		29	+ return !params;
		30	+}
		31	+
		32	+bool I2C_Scan_Command::execute(CLI &cli) {
		33	+ if (_address < 127) {
		34	+ if (_address == 0) cli.println(F("Scanning I2C..."));
		35	+ Wire.beginTransmission(_address);
		36	+ uint8_t error = Wire.endTransmission();
		37	+
		38	+ if (error == 0) {
		39	+ cli.print(F("I2C device found at address 0x"));
		40	+ if (_address < 0x10) cli.print("0");
		41	+ cli.println(_address, HEX);
		42	+ _found++;
		43	+ } else if (error == 4) {
		44	+ cli.print(F("Unknown error at address 0x"));
		45	+ if (_address < 0x10) cli.print("0");
		46	+ cli.println(_address, HEX);
		47	+ }
		48	+ _address++;
		49	+ return true;
		50	+ } else {
		51	+ if (_found == 0)
		52	+ cli.print_P(PSTR("No I2C devices found"));
		53	+ return false;
		54	+ }
		55	+}
		56	+
		57	+
		58	+I2C_Dump_Command::I2C_Dump_Command(CLI & cli) : CLI_Command(cli,
		59	+ PSTR("i2c_dump"), PSTR("Display I2C EEPROM/Memory in HEX and ASCII"),
		60	+ PSTR("Usage: i2c_dump 0x<id> <size> [<skip>] [single]\n"
		61	+ "where:\t<id>\tHEX I2C device ID\n"
		62	+ "\t<size>\tsize of memory\n"
		63	+ "\t<skip>\t(optional) start offset\n"
		64	+ "\tsingle\tto enforce 1-byte addressing")) { };
		65	+
		66	+bool I2C_Dump_Command::setparams(const char *params) {
		67	+ if (params && (params++) == '0' && (params++) == 'x') {
		68	+ if ((params = CLI_STR_parse_HEX_byte(params, _address)) && *params == ' ') {
		69	+ if(params = CLI_STR_parseInt(CLI_STR_skipSep(params), (int &)_length)) {
		70	+ _offset = 0;
		71	+ _large = _length > 0xff;
		72	+ if (*params == ' ') {
		73	+ params = CLI_STR_skipSep(params);
		74	+ if(const char *p = CLI_STR_parseInt(params, (int &)_offset))
		75	+ params = CLI_STR_skipSep(p);
		76	+ if (strcmp_P(params, PSTR("single")) == 0) {
		77	+ if (_large) return false;
		78	+ params += 6;
		79	+ }
		80	+ }
		81	+ return *params == 0;
		82	+ }
		83	+ }
		84	+ }
		85	+ return false;
		86	+}
		87	+
		88	+bool I2C_Dump_Command::execute(CLI &cli) {
		89	+ uint8_t buffer[16], len = 0;
		90	+
		91	+ Wire.beginTransmission(_address);
		92	+ if (_large) Wire.write((uint8_t)(_offset >> 8)); // MSB
		93	+ Wire.write((uint8_t)(_offset & 0xff)); // LSB
		94	+ if (Wire.endTransmission() != 0) {
		95	+ cli.print(F("No I2C device at 0x"));
		96	+ cli.print(_address, HEX);
		97	+ cli.println();
		98	+ return false;
		99	+ }
		100	+
		101	+ if (_offset == 0) cli.println(F("I2C EEPROM/Memory: "));
		102	+
		103	+ Wire.requestFrom(_address, (uint8_t) (_length - _offset < sizeof(buffer)) ? _length - _offset : sizeof(buffer));
		104	+ while (Wire.available() && len < sizeof(buffer)) buffer[len++] = Wire.read();
		105	+
		106	+ cli.print_mem(_offset, buffer, len);
		107	+ _offset += len;
		108	+ return _offset < _length;
		109	+}
		110	+